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Abstract 


T-SB  (for  Layered  System  Building)  is  an  integrated  set  of  facilities  for  aiding  in  the 
construction  of  highly-modular,  multi-layered,  implementation-independent  Lisp  systems.  It 
provides  for  conditional  inclusion  of  source  text,  documentation  production,  automated 
declarations,  and  "high-level"  definitions.  Lisp  code  compiled  with  LSB  in  general  does  not 
require  LSB  in  its  run-time  environment.  LSB  has  been  in  use  for  some  time  in  PDF- 10  Maclisp, 
is  operational  in  Multics  Maclisp  and  Lisp  Machine  Lisp,  and  is  being  developed  for  NIL. 
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1.  Introduction 

LSB  (for  Layered  System  Building)  is  an  integrated  set  of  facilities  for  aiding  in  the 
construction  of  highly-modiilar,  multi-layered,  implementation-independent  Lisp  systems.  It 
provides  for  conditional  inclusion  of  source  text,  documentation  production,  automated 
declarations,  and  "high-level"  definitions.  Lisp  code  compiled  with  LSB  in  general  docs  not 
require  LSB  in  its  run-time  environment.  LSB  has  been  in  use  for  some  time  in  PDP-10  Maclisp, 
is  operational  in  Multics  Maclisp  and  Lisp  Machine  Lisp,  and  is  being  developed  for  NIL. 

ITie  basic  idea  is  that  when  a  programmer  defines  something,  it  should  not  be  necessary  to 
declare  it  separately;  after  all,  the  definition  itself  usually  makes  a  separate  declaration  redundant. 
Definitions  should  be  able  to  be  located  where  style  and  modularity  dictate;  their  positioning, 
both  with  respect  to  location  in  a  particular  source  file  and  the  position  in  the  file,  should  not 
depend  on  the  basis  of  the  vagaries  of  the  Lisp  compiler.  Documentation,  especially  on  a  local 
level,  is  also  best  positioned  in  close  proximity  to  what  it  describes,  lliis  allows  for  ease  of 
updating  the  definition  and  the  documentation  together,  reducing  the  tendency  for  them  to 
diverge  as  development  progresses. 

It  is  becoming  increasingly  common  for  the  same  source  code  to  be  used  in  different  Lisp 
implementations.  The  programmer  should  be  able  to  easily  make  use  of  implementation-specific 
facilities,  by  having  some  mechanism  for  conduiomlizing  tlie  source  code.  On  the  other  hand,  the 
use  of  many  facilities,  particularly  in  the  realm  of  function  definition  and  type  declarations,  can 
be  specified  at  a  high  level,  independent  of  any  particular  Lisp  implementation. 

In  LSB,  definitions  are  aggregated  into  modules,  and  modules  into  systems.  From  tlie  source 
text  for  a  module,  LSB  derives  the  information  necessary  to  compile  and  run  code  of  that 
module,  of  other  modules  of  that  system,  and  of  modules  in  other  systems  which  utilize  that 
system.  A  sample  LSB  system  can  be  found  in  chapter  15,  page  78. 

l.I  Conventions  of  this  Manual 

The  reader  of  tliis  manual  is  expected  to  have  a  working  knowledge  of  Lisp,  particularly  one 
of  the  dialects  for  which  LSB  exists  (Lisp  Machine  Lisp  [I.MMan],  M.aclisp  [Moonual],  and  NIL 
(VAX)  (NILDocJ).  Terms  which  are  in  common  use  in  these  dialects  will  be  used  freely  here. 

Hie  LSB  environment  establishes  an  initial  default  input  radix  of  decimal.  Integers  in  text 
and  in  examples  should  be  so  interpreted  except  where  explicitly  countcrindicatcd. 

In  Lisp  code  examples,  the  symbol  =>  should  be  read  as  "evaluates  to",  and  the  symbol 
=  =  >  as  "macro-expands  to”. 

All  Lisp  code  in  this  manual  is  written  in  lower  case.  Although  most  of  the  Lisp 
implementations  LSB  runs  in  canonicali/e  lower-case  symbols  to  upper-case.  Multics  Maclisp  docs 
not.  All  LSB  routines,  m.icros,  and  variables  arc  lower  case  in  Multics.  In  general,  in  a 
reasonably  standard  reading  environment,  atomic  symbols  may  be  typed  in  just  as  they  arc  shown 
in  here.  All  atomic  symbols  in  this  manual  which  arc  shown  with  colons  in  their  names,  such  as 
ipreviously  loadod  or  Isb  token -equal,  arc.  in  Maclisp,  actually  symbols  with  exactly  that  print- 
name,  colon  and  all.  In  I  isp  iinplcmcniaiions  with  packages,  the  package  prefix  part  of  Uic  name 
is  intended  to  be  interpreted  as  just  that.  I  bus,  the  same  source  code  can  refer  to  these  names  in 
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the  same  way  in  different  Lisp  implementations. 

'fhe  null  value  is  represented  by  the  symbol  nil,  and  its  canonical  complement  by  t.  In  the 
NIL  implementation,  LSB  will  accept  the  atomic  symbol  t  in  various  places  as  meaning  #t  or 
"truth".  Most  notable  of  these  are  as  an  "argument"  to  a  two-state  definition  option,  such  as  do- 
argument-type-checking,  and  as  the  predicate  of  a  diversion  stream.  No  such  compensation 
will  be  guaranteed  for  the  symbol  nil;  if  one  is  writing  source  code  to  be  used  in  NIL,  use  () 
instead. 

Certain  Lisp  implementations  have  missing  functionality,  which  makes  it  difficult,  inefficient, 
or  impossible  to  implement  certain  LSB  features.  These  deficiencies  are  noted  in  this  manual 
without  further  explanation.  Most  notable  in'  this  respect  is  Multics  Maclisp,  which  has  a  severe 
lack  of  functionality  in  dealing  with  the  Multics  file  system. 

In  various  places  in  this  manual,  atomic  symbols  may  be  referred  to  as  keywords,  and  the 
terms  keyword  equality  and  token  equality  may  be  used.  LSB  token  equality  is  simply  case- 
independent  print-name  equality;  this  is  used  in  many  contexts  to  make  things  independent  of 
packages  or  case  distinctions.  Keyword  equality  is  token  equality  extended  to  allow  synonyms  (a 
table  of  which  is  given  in  chapter  16).  T'he  internal  LSB  primitives  used  for  this  arc  documented 
in  section  12.1,  page  63. 
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2.  Overview 

Hiis  chapter  is  intended  as  a  descriptive  explanation  of  how  LSB  works  and  what  it  can  do. 
It  should  provide  a  sufficient  basis  for  casual  and  simple  use  of  LSB.  Precise  and  much  more 
detailed  definitions  of  the  facilities  presented  here  occur  in  later  chapters. 

2.1  Dcrivability 

One  of  the  primary  precepts  of  LSB  is  derivabilily.  That  is,  it  is  assumed  (although  not 
necessarily  enforced)  that  all  the  information  necessary  to  understand,  compile,  and  execute  some 
code  is  derivable  from  a  single  source  text.  Thus,  LSB  provides  facilities  for 

conditional  inclusion 

One  may  specify  that  parts  of  the  source  text  are  applicable  only  in  certain  environments 
(e.g.,  certain  Lisp  implementations),  and  therefore  a  single  source  text  may  serve  as  the 
source  in  many  environments. 

text  diversion 

Portions  of  the  source  text,  while  treated  as  comments  by  Lisp  itself,  may  be  copied 
elsewhere  (possibly  transformed),  perhaps  to  serve  as  documentation  for  the  code. 

form  diversion 

Lisp  objects  may  be  sent  to  various  places,  to  provide  information  needed  for 
compilation,  execution,  debugging,  etc. 

combined  definition  and  declaration 

The  definition  facilities  in  LSB  use  the  form  diversion  mechanism  to  produce  the 
declarations  appropriate  to  the  type  of  object  being  defined  (e.g.,  routine,  macro, 
variable).  All  of  the  information  needed  for  these  declarations  can  be  included  in  the 
definition  syntax  itself,  obviating  the  need  for  separate,  and  potentially  implementation- 
dependent,  declarations. 

module  and  system  organization 

Modules,  corresponding  to  the  source  files,  arc  grouped  into  systems  and  share 
information  which  need  not  be  propagated  elsewhere.  Definitions  of  systems  specify  what 
other  LSB  systems  Jiey  use,  and  may  be  used  to  customize  the  processing  (e.g.,  loading, 
compilation)  environment  to  be  used  for  each  module. 

2.2  Visibility  Classes 

LSB  associates  with  every  defined  object  (e.g.,  routine,  macro,  or  variable)  a  visibility  class. 
'niis  is  essentially  an  indicator  of  ”how  far"  infunnation  about  the  object  should  propagate.  The 
three  visibility  classes  provided  arc: 

private  restricted  to  the  module 

system  restricted  to  the  system  containing  the  module 

public  intended  for  explicit  use  by  users  of  this  system 

I  he  system  visibility  class  used  to  be  named  intrasystem.  t  hat  name  is  still  accepted,  and 
occurs  liequcnily  in  existing  code:  deline -intrasystem -routine  is  defined  to  be  the  s^ime  as 
define- system  routine,  and  intrasystem -compilation  is  synonomous  as  a  keyword  with  system- 
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compilation,  for  example. 

l.SB,  using  visibility  classes,  does  not  attempt  to  resolve  naming  conflicts.  It  makes  no  use  of 
packages  or  other  name  resolution  techniques,  where  such  exist.  A  visibility  class  is  used  only  for 
informational  (c.g.,  declaration  and  documentation)  purposes,  ('lliis  may  not  be  the  case  in  future 
Lisp  implementations  where  package  organization  is  not  limited  to  a  strict  hierarchy.) 

2.3  DeHnitions 

Everything  in  LSB  gets  "defined",  even  special  variables.  An  LSB  definition  provides  a  means 
for  specifying  all  necessary  information  about  what  is  being  defined,  and  thus  allows  that 
information  can  be  localized.  This  includes  such  things  as  default  or  required  initialization  (for 
special  variables),  argument  types  (for  routines),  and  the  value  type  (for  both). 

2.3.1  Routines 

Routine  definition  is  LSB’s  counterpart  to  Lisp’s  function  definition.  In  a  routine  definition, 
rather  than  specifying  a  function  name  and  an  argument  list,  one  specifies  a  prototype  call.  ITiis 
is  a  form  which  describes  what  a  call  to  that  routine  looks  like.  For  example, 
(print-decimal-number  number  (optional  stream)) 
describes  a  call  to  the  routine  print-decimal-number,  which  can  take  one  or  two  arguments. 
ITie  prototype  call  tells  LSB  what  variables  ("formal  parameters")  are  to  be  bound,  the  data  types 
of  tliosc  variables,  how  many  arguments  the  routine  may  take,  the  data  types  of  those  arguments, 
and  how  to  process  a  call  to  the  routine. 

Call  processing  is  the  mapping  of  a  call  into  a  lambda  expression  which  takes  a  fixed  number 
of  arguments.  Because  of  the  information  available  to  LSB,  it  is  able  to  decide  at  what  point 
(from  compile  time  to  run  time)  this  mapping  may  be  made  most  advantageously. 

A  full  definition  of  print-decimal-number  might  look  like 
(define -public-routine  ( pri nt-decimal -number 

number  (optional  stream)) 

((lambda  (base  •nopoint) 

(princ  number  stream)) 

10.  t)) 

print-decimal-number  is  a  routine,  as  opposed  to  (for  example)  a  macro.  When  only  one 
argument  is  given  to  it,  stream  will  be  bound  to  nil.  Ihe  prototype  call  might  have  been  written 
as 

( pr  i  nt -  dec imal -number 

number  (optional  stream  standard-output)) 
if  it  were  desired  that  the  value  of  the  variable  standard -output  should  be  used  in  lieu  of  a 
missing  second  argument. 

I  he  following  clcfincs  the  routine  square$.  which  operates  only  on  flonums: 

( def ine-publ ic-routine  (squares  (flonum  n)) 

(declarations  (value-type  flonum)) 

( *$  n  n ) ) 

It  also  shows  the  declaration  fomiat  for  LSB  routine  and  macro  definitions.  In  general,  tlic  edr 
of  the  declarations  form  is  an  a-list  t)f  keywords  and  any  other  infonnation  specific  to  that 
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declaration  clause.  The  value-type  declaration  says  that  this  routine  always  returns  a  flonum. 
declarations  may  be  abbreviated  as  dels.  Multiple  declarations  forms  may  be  used,  as  long  as 
tliey  all  precede  any  code. 

macros  may  be  defined  in  a  form  similar  to  routines;  a  prototype  macro  call  has  the  same 
format  as  a  prototype  routine  call. 

( def i ne -pub! i c-macro  { f oo  x) 

(list  ’caddar  x)) 

defines  foo  as  a  macro  that  is  synonymous  with  caddar. 

2.3.2  Variables 

In  LSn,  one  can  "define"  special  variables  as  well  as  routines.  Having  a  definition  provides  a 
distinct  locus  for  giving  attributes  to  the  variable.  In  the  definition,  one  may  specify  such  things 
as  the  type  of  the  variable,  and  its  initialization.  The  expression 
(de fine-public-variable  *print-stm-props? 

(default-initialization  nil)) 

defines  the  special  variable  *  print -stm- props?.  A  variable  definition  provides  for  the  initialization 
of  the  variable,  if  any,  and  appropriate  declarations  are  generated  to  tell  the  compiler  about  the 
variable.  The  default -initialization  (or  default-init)  declaration  says  that  if  the  variable  is  not 
valued,  it  should  be  set  to  the  value  of  the  form  specified,  in  this  case  nil.  One  could  cause  the 
variable  to  be  unconditionally  initialized  by  using  initialization  (or  init)  instead,  1110  type  can  be 
specified,  as  in 

(define-system-variable  ♦stack-level 
(value-type  fixnum) 

(default-init  0)) 

2.4  Conditional  Inclusions 

I. SB  provides  a  mechanism  for  conditional  inclusion  of  forms  or  subforms  in  a  source  file, 
using  ilic  characters  left  brace  (()  and  right  brace  ()),  When  a  left-brace  is  encountered  by  the 
l  isp  reader,  a  form  (the  inclusion  test)  is  read.  That  form  should  be  a  list  whose  car  is  an 
atomic  symbol  (the  inclusion  tester).  The  inclusion  test  is  interpreted  to  determine  either  "success" 
or  "failure".  A  failing  test  causes  all  of  tlie  text  through  the  matching  right-brace  to  be  discarded, 
clfectivcly  making  it  disappear  from  the  input  stream  (as  far  as  Lisp’s  read  is  concerned). 
Otherwise,  the  text  is  left  alone,  and  the  matching  right-brace  will  be  ignored  (treated  as  a  blank) 
when  encountered.  Ihus, 

( def i ne-pri vate-rout i ne  (make-a-f rob  size) 

{(only-for  Lispm)  (make-array  size  ’:type  ’art-q)} 

((only-for  Maclisp)  (•array  nil  t  size)}) 

is  like  having 

( def i ne-pri vate -routine  (make-a-frob  size) 

(make-array  size  ’.type  ’art-q)) 
on  tlic  Lisp  M.ichine,  but 

(define-private  routine  (make-a-frob  size) 

(•array  nil  t  s  i  ze  ) )  /  jr 

in  Maclisp.  1  he  only-for  inclusion  tes'tcr  chocks  for  implementation  fealurcs  of  the  einiionment, 
e.g.,  (status  feature  Lispm). 
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Additionally,  if  the  inclusion  test  is  one  of  the  atomic  symbols  --  or  then  the  (.ext 

within  the  braces  is  always  ignored,  and  acts  as  a  comment.  The  --  keyword  is  an  "em-dash", 
obscurely  derived  from  ADA.  ITie  is  for  use  in  "file  property  lists”,  as  used  on  the  l  isp 
Machine,  and  also  by  the  Emacs  editor.  Thus,  one  may  put  at  the  very  beginning  of  a  file 
something  like 

{-•-  Mode-.Lisp;  Package ;  Format 
random  text  treated  as  comments} 

One  may  use  a  logical  composition  of  implementation  features  in  place  of  a  simple  one.  hor 
example, 

{(only-for  (and  string  Multics))  ...} 
is  the  same  as 

{(only-for  string)  {(only-for  Multics)  ...}} 

Any  composition  of  and,  or,  and  not  may  be  used  in  constructing  these  "feature  predicates". 
Multiple  "arguments"  to  only-for  are  treated  as  an  implicit  or;  thus,  (only-for  Maclisp  Lispm) 
is  equivalent  to  (only-for  (or  Maclisp  Lispm)). 

{(except-for  Lispm)  . . .} 
is  the  same  as 

{(only-for  (not  Lispm))  ...} 

In  general,  (except-for  frob-I  frob-2  ...  frob-n)  is  the  complement  of  (only-for  frob-I  frub-2  ... 
frob-n).  There  are  some  other  inclusion  testers,  similar  to  only-for  and  except-for.  which  allow 
the  use  of  multiple  "feature  environments",  in  order  to  facilitate  cross  compilation.  These  are 
discussed  in  chapter  4.  page  24. 

An  inclusion  test  which  is  an  atomic  symbol  (and  not  --  or  -*-)  is  treated  as  a  simple 
implementation  feature  test,  and  interpreted  as  (only-for  test).  Thus, 

{Lispm  . . .} 
is  the  same  as 

{(only-for  Lispm)  . . . } 

C'ondiiional  inclusions  may  conditionalize  any  number  of  forms.  ITiey  may  also  be  nested,  to 
allow  successive  selections  and  defaultings,  as  in 

( def ine-pri vate-routine  (make-a-frob  size) 

{(only-for  L i spm) 

(make-array  size  ' : type  ’art-q) 

} 

{(except-for  Lispm) 

{(only-for  NIL) 

(make-vector  size) 

} 

{(except  for  NIL) 

(♦array  nil  t  size) 

} 

} 

) 
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2.5  Diversion  Streams 

Diversion  streams  are  an  abstraction  used  by  l,SB  to  handle  derivation  (see  section  2.1).  An 
I.SB  definition  processor  partitions  the  various  pieces  of  information  it  gathers,  according  to  their 
intended  uses,  and  then  "sends”  them  to  appropriate  diversion  streams.  The  effects  of  this 
partitioning  range  from  immediate  evaluation,  to  outputting  text  into  a  file,  to  compiling  Lisp 
forms  into  a  file. 

In  the  routine  definition 

(def ine-publ ic-routine  (squares  (flonum  n)) 

(dels  (value-type  flonum)) 

( •$  n  n ) ) 

there  arc  two  different  kinds  of  information  data  which  need  to  be  dealt  with.  One  is  the 
definition  of  squareS  itself,  and  the  other  is  the  set  of  declarations  needed  to  compile  squareS 
and  calls  to  squareS.  Using  primitive  Maclisp,  that  would  be  written  out  as 
(declare  (•expr  squareS)  (flonum  (squareS  flonum))) 
and 

(defun  squares  (n) 

(declare  (flonum  n)) 

( •$  n  n) ) 

LSB  arranges  for  declarations  simitar  to  those  in  the  declare  form  above  to  be  sent  to  the 
compilation -environment  and  pubdcl  diversion  streams.  The  first  acts  as  a  no-op  when  the 
definition  is  being  processed  at  run  time,  but  at  compile  time  causes  "immediate  evaluation",  as  if 
the  compiler  had  seen  a  corresponding  declare  form.  The  pubdcl  (public  declarations)  diversion 
stream  also  does  nothing  at  run  time.  At  compile  time,  it  causes  the  declaration  forms  to  be 
written  into  a  file,  so  that  they  can  be  used  for  the  compilation  of  other  modules.  Iherc  is  a 
declaration  diversion  stream  for  each  visibility  class;  complementing  pubdcl  are  sysdcl  (system 
declarations)  and  moddcl  (module  declarations). 

In  addition  to  form  diversion  streams,  tliere  are  also  diversion  streams  for  text,  'fhree 
standard  text  diversion  streams  arc  pubdoc,  sysdoc.  and  moddoc.  Text  diversion  streams  are 
used  in  a  different  manner  than  form  diversion  streams:  an  extension  of  the  conditional  inclusion 
mechanism  allows  the  excluded  text  to  be  diverted  to  any  number  of  of  these  streams.  Typically, 
dicse  diversion  streams  simply  output  the  text  to  a  file.  By  means  of  text  diversion,  a  single 
source  can  contribute  to  multiple  levels  of  documentation.  ITic  documentation  files  of  tlie  same 
visibility  class  for  several  modules  could  be  recombined  to  produce  (say)  a  manual.  In  this 
manner,  one  can  have  the  documenuuion  of  some  code  or  of  a  mixiule  itself  Iwated  with  the 
source  text  it  describes.  For  example,  one  might  include  in  some  module  something  like 
{( publ i c -documentation) 

.chapter  "The  Matcher" 

The  pattern  matcher  In  FROBOZZ  Is  guaranteed  to 
solve  all  of  the  world’s  problems.  In  order  to  do  this, 
blah  blah  blah.} 
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2.6  Dcrinition  Availability 

When  objects  arc  defined,  it  is  sometimes  necessary  to  specify  where  the  definition  is  to  be 
diverted  to.  The  most  common  ease  is  that  of  a  routine  which  is  called  by  a  macro.  LSB  needs 
to  be  told  to  divert  the  routine  to  the  same  placcfs)  that  the  macro  goes,  fhe  needed -for 
declaration  clause  handles  this,  llierc  may  also  be  random  forms  (e.g.,  calls  to  defprop)  which 
need  to  be  diverted  in  a  similar  manner;  the  forms- needed -for  special  form  will  do  the  same 
for  arbitrary  forms. 

Consider,  for  example, 

(def ine-privata-routine  (bar  x  y) 

...) 

( def i ne-pubUc-macro  (foo  arg) 

(bar  arg  t)) 

Each  definition  type  (e.g.,  define -visc/ass- routine,  define -v/sc/asi- macro)  has  a  default 
needed -for  declaration,  which  may  be  overridden,  or  just  added  to  (by  use  of  the  also- 
needed-for  declaration).  In  this  example,  the  simplest  way  to  achieve  the  desired  effect  is  to 
define  bar  using  the  also -needed -for  declaration 

( def i na-pri vato-rout 1 na  (bar  x  y) 

(dels  (also-needed-for  public-compilation)) 

...) 

which  says  that  not  only  do  we  need  the  definition  of  bar  when  we  are  running  (the  default  for 
ordinary  routine  definition),  but  also  during  "public  compilation".  The  way  the  default  declaration 
could  be  touilly  overridden  (in  this  case  for  the  same  effect)  is 
( def ine- pri vata-routine  (bar  x  y) 

(dels  (needed-for  running  public-compilation)) 

...) 

The  needed-for  keywords  which  may  be  used  are; 
running 

This  corresponds  to  the  toplevel  diversion  stream.  The  definition  will  be  output  in 
the  compiled  output  file,  or  to  the  interpreter. 

interpretation 

ITiis  corresponds  to  the  interpreter  diversion  stream,  llie  definition  will  be  made  at 
run  time,  but  not  in  the  compiled  output  file  (unless  that  is  implied  in  some  other 
way). 

public  -compilation 
system  -  compilation 
private  -  compilation 

Ihosc  m.ip  into  fici/i  the  declaration  divcrsirin  stream  of  the  appropriate  visibility  class 
(pubdcl.  sysdcl.  or  moddcl).  tlie  compilation -environment  diversion  stream. 

compilation 

Just  like  the  previous  three,  with  the  visibility  class  detennined  from  that  of  the 
object  being  defined. 

(jiiy  tlivirsian  sinvin  name 

Hus  is  to  he  used  in  case  the  above  keywords  arc  insufficient,  tis  they  would  be  if 
one  is  defining  one's  own  diversion  streams. 
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A  typical  situation  where  also -needed -for  and  forms -needed -for  are  called  for  is 
( defi na-sys tern-macro  (hack-it  a  b) 

(do-it-up  a  b  (get  a  ’hack))) 

( def i ne-pri vate-routine  (do-it-up  x  y  z) 

(dels  ( al so-needed-for  system-compilation)) 

...) 

( forms -needed-f or  (running  system-compilation) 

(defprop  foo  foo-hacker  hack) 

(defprop  bar  bar-hacker  hack) 

(defprop  baz  baz-hacker  hack)) 

Occasionally  one  may  have  a  routine  or  variable  which  may  be  implicitly  referenced  at  a 
higher  visibility  class  than  it  is  defined  at.  Obviously  one  could  change  its  visibility  class,  but  that 
may  not  be  the  appropriate  solution,  lypically.  the  visibility  class  corresponds  most  closely  to  the 
documentation;  it  is  chosen  on  the  basis  of  who  should  know  about  it.  Take  the  case  of  a  macro 
hairy-frob,  which  expands  into  code  which  calls  the  internal  routine  hairy -frob- internal: 
(define-public-macro  (hairy-frob  this  that) 

(list  ’ hai ry-f rob-internal 

this  that  t  0  ’’hairy-frob)) 

In  this  situation,  the  declarations  for  hairy -frob -internal  need  to  be  public.  Ihe  proper  way  to 
achieve  this  is  to  use  the  referenced-at-visibility-class  (or  reference)  declaration  in  the 
definition  of  hairy -frob -internal: 

( def ine-pr i vate-routine  (hairy-frob- internal 

this  that  flag 
start-count  caller) 

(dels  (reference  public)) 

...) 

2.7  Modules  and  Systems 

In  order  to  utilize  the  information  derived  from  other  modules  during  the  compilation  of  one, 
LSI)  requires  tliat  modules  be  organized  into  sysfrim.  Hach  system  must  be  defined  to  LSB,  to 
say  what  other  systems  it  utilizes,  what  •'.lOdulcs  it  contains,  where  to  find  it  in  the  file  system, 
and  environmental  options,  such  as  what  input  radix  should  be  used.  One  puts  a  form  like 
(module  print  xlms) 

at  the  front  of  a  module  to  tell  LSB  what  module  and  system  the  file  corresponds  to;  in  this 
case,  the  print  module  of  the  xlms  system.  (Module  and  system  names  arc  compared  by  LSB  for 
token  equality.)  When  this  form  is  processed  by  the  Lisp  interpreter  or  compiler,  LSB  sets  up  the 
environment  necessary  for  the  interpretation  (loading)  or  compilation  of  the  remainder  of  the  file, 
as  specified  by  the  system  definition.  If  the  source  code  is  to  be  used  in  a  Lisp  implementation 
whicii  supports  "file  properly  lists"  (such  as  Lisp  Machine  Lisp),  one  should  also  use  the  Isb 
option  in  the  file  property  list; 

{-*-  Mode-.Lisp;  LSB-.Print.XLMS  l-Jun-81 

Copyright  (c)  1981  by  Grandiose  System  Building 
and  Massachusetts  Institute  of  Technology. 

All  rights  reserved.) 

This  will  then  allow  many  other  file  property  list  options  to  he  derived  from  tlte  LSB  system 
definition;  most  impoilanl  of  these  arc  the  package,  rcadlablc,  and  input  radix. 
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System  definitions  typically  reside  each  in  a  separate  file:  LSB  has  search  and  defaulting  nilcs 
for  finding  them  when  necessary,  and  also  has  initial  knowledge  of  a  large  number  of  commonly 
used  systems.  The  system  definition  typically  resides  on  the  directory  with  the  same  name  as  the 
system  name,  a  (first)  filename  the  same  as  the  system  name,  and  a  file-type  of  system.  I.SB  will 
also  look  for  it  on  the  directory  which  the  source  file  is  being  loaded  or  compiled  from.  For 
example, 

(def ine-system  string 
(directory  amber) 

(built-on  loop  Ibind) 

(users-implicitly-need  user-hunk) 

(modules  (string  ( needed-for-oser-compi 1  at i on ) )  strfn  char)) 
is  the  system  definition  for  the  string  system;  it  resides  on  the  amber  directory,  as  does  the 
source  for  all  of  the  modules  (string,  strfn,  and  char). 


2.7.1  Pathnames 

I.SB  allows  one  to  interact  with  the  host  file  system  in  such  a  way  that  in  many  cases  the 
same  LSB  specification  suffices  in  differing  and  incompatible  implementations,  lliis  mechanism  is 
based  on  the  assumption  that  the  following  "components"  of  a  pathname  exist  as  a  superset  of  all 
those  a  particular  LSB  implementation  might  handle: 

host  This  is  the  name  of  the  "host  machine"  the  file  is  to  be  obtained  from  (or  sent  to). 

Ihis  is  necessary  in  implementations  where  one  may  need  to  reference  multiple  hosts, 

such  as  the  Lisp  Machine. 

device  Whatever  is  meant  by  a  "device"  in  the  host  implementation. 

directories 

LSB  has  provision  for  specification  of  a  directory  path. 

names  LSB  has  provision  for  multiple  filenames. 

file-type 

The  "type"  of  the  file,  as  used  (for  example)  rOPS-20. 

version 

The  version  number  of  the  file. 

Thus,  the  rOPS-20  pailinamc  "PS:<MACLISP>DEFMACRO.FASL.259"  has  a  device  of  PS.  a 
single  directory  of  MACLISP,  a  single  name  of  DEFMACRO.  a  file-type  of  FASL.  and  a  version 
of  259.  Iliat  same  pathname  referenced  from  a  I  isp  Machine  might  also  need  to  have  a  host 
specified.  In  general,  LSB  allows  these  components  to  be  specified  or  defaulted  separately,  so  that 
the  same  LSB  specification  suffices  in  difTcrent  environments  when  tJie  corresponding  components 
arc  the  same. 


M'  .1  SBI)()C;OVi:i<  101 


29-,HlN-Kl 


1.SB  Manual 


11 


'Ilie  System  Definition 


3.  The  System  Definition 

The  system  definition  is  where  information  not  specific  to  individual  routines,  macros,  or 
variables  is  kept.  It  tells  l.SB  what  other  systems  the  one  in  question  is  buili  on,  where  various 
things  (including  source  files)  reside  in  the  file  system,  what  Lisp  environmental  options  should  be 
in  clTeLt,  and  how  divei^sion  streams  should  behave;  much  of  this  may  be  specified  either  per- 
module  or  per-system.  For  example, 

(  def i ne-system  write 

(directory  format) 

(built-on  loop  Ibind) 

(modules  write)) 

defines  the  system  write,  which  uses  (is  buili  on)  the  systems  named  loop  and  Ibind,  contains  a 
single  module  named  write,  and  resides  on  the  format  directory. 


3.1  The  System  Definition  Location 

When  l.SB  needs  the  definition  of  a  particular  system  (say  xlms),  it  attempts  to  find  it  if  it  is 
not  already  known.  One  way  it  might  know  where  to  look  is  through  the  use  of  the  define- 
system- location  macro: 

def ine-systsm-locatlon  Macro 

(define -system -location  system-name  location)  tells  LSB  that  the  system  definition  for 
system- name  may  be  found  in  the  file  named  by  the  pathname  location.  For  our  example, 
someone  could  have  done 

( def ine-system-location  xlms  "XLMS;XLMS  SYSTEM") 
since  "XLMSiXLMS  SYSTEM"  is  the  pathname  of  the  file  which  contains  the  system 
definition  for  xlms  on  the  MIT-MI.  host.  When  this  form  is  seen  by  the  compiler  (at 
top-level,  like  a  defun)  it  is  treated  such  that  the  location  of  the  system  definition  is 
defined  at  compile  time,  and  also  when  the  compiled  output  file  is  loaded  (that  is.  it  uses 
(eval-when  (eval  compile  load)  ...)  implicitly). 

The  patimamc  specified  with  define -system -location  need  not  be  complete;  it  may  contain 
unspecified  components,  which  will  get  filled  in:  LSB  has  searching  and  defaulting  rules  which  in 
many  cases  obviate  the  need  for  define-system-locafion  completely. 


3.2  Searching  for  the  System  Definition 

When  LSB  docs  not  already  know  a  system  definition,  it  searches  for  it  in  a  prescribed 
manner.  This  searching  is  done  even  if  a  system  definition  location  has  been  specified,  because 
that  system  definition  may  have  missing  components;  for  instance,  tlic  Brand -X  system  definition 
location  may  only  sbitc  that  the  filename  to  look  for  is  brandx.  LSB  maintains  a  dynamic  stack 
of  where  it  should  search:  each  entry  corresponds  to  a  directory  path  (and  device  and  host, 
where  implemcniationally  appropriate).  The  entries  arc  pushed  when  LSB  recursively  looks  at 
sysieins.  for  instance  when  it  is  establishing  the  compilation  environment  for  a  module;  the  details 
of  this  procedure  are  described  later.  In  any  case,  the  first  directory  to  be  looked  at  will  be  tlic 
directory  with  the  same  n.ime  as  the  system.  Where  appropriate,  the  device  will  be  tlic 
"c. monie  d"  device  foi  die  implementation  (e.g..  PS  for  KlI’S  20),  and  the  host  will  be  the 
current  def.udt  host,  however  that  is  maintained.  The  last  place  to  be  looked  at  will  be  the 
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directory  (including  the  device  and  host  components)  where  LSB  is  kept.  Somewhere  in  the 
middle  will  be  the  directory  (and  device  and  host)  where  the  source  file  being  processed  was 
found.  The  searching  involves  iterating  down  this  search  list;  of  the  components  missing  from  the 
system  definition  location  (if  there  is  one),  missing  directory,  device,  and  host  components  are 
filled  in  from  the  search  list,  a  missing  filename  defaults  to  the  system  name,  and  a  missing  file- 
type  defaults  to  system.  A  file  with  name  of  Isbsystems  is  also  looked  for  (the  file  type  will  be 
the  canonical  "lisp  source  file"  type,  c.g.  lisp  on  Miillics,  ">"  on  ffS,  l.SP  on  TOPS-20).  If 
during  this  procedure  a  system  definition  location  is  found  for  the  system  (and  one  was  not 
already  known),  the  searching  starts  over  again  using  that  system  definition  location. 

Take,  for  example,  the  xlms  system,  which  exists  on  MIT-ML.  The  first  place  I.SB  will  look 
in  the  absence  of  a  system  definition  location  will  be  "DSK:XLMS:XLMS  SYSTHM"  —  this  is  in 
fact  where  the  system  definition  for  xlms  is  kept. 

There  is  one  other  way  in  which  LSB  may  be  told  where  to  find  a  system  definition:  it  may 
be  specified  with  the  name  of  the  system. 

(module  print  (xlms  "XLMS-.TEST  SYSTEM")) 

{ def ine-system  write 
(directory  format) 

(built-on  (loop  "LISPM2:")  Ibind) 

(modules  write)) 

A  location  specified  in  this  way  overrides  any  known  system  definition  location;  it  is  not  used  to 
aid  the  defaulting  process  for  finding  the  definition  of  that  system,  but  rather  to  respecify  it,  if 
(for  example)  one  wants  to  test  a  perturbed  system  definition  or  test  a  new  system  by  that  name. 
For  simply  supplying  a  system  definition  location  when  one  might  not  be  known,  the  Isbsystems 
file  should  be  used. 

The  Isbsystems  file  can  be  used  for  various  purposes.  It  can  be  used  to  consolidate  all  of 
the  system  definitions  of  systems  which  reside  on  tlic  same  directory.  It  can  also  be  used  to 
define  the  system  definition  locations  of  systems  which  systems  on  that  directory  arc  built-on  (or 
otherwise  reference),  lliis  last  is  often  necessary  because  otherwise  LSB  might  have  no  handle  on 
where  to  look  for  some  system  definition,  if  the  referencing  module  is  on  a  difTerciU  directory. 
One  solution  to  where  to  look  is  simply  to  have  the  system  definition  location  pre-defined  to  LSB. 
Systems  which  may  be  of  general  use  are  welcome  additions,  llie  pre-defined  systems  arc  in  the 
Isbsystems  file  on  LSB's  directory.  On  ffS,  this  is  the  file  named  ”I)SK;LSB;LSBSYS  >",  and 
on  Multics  ">udd>Matlilab>LSB>lsbsysicms.lisp".  These  files  have  identical  contents,  which  are 
conditionali/ed  for  the  various  implementions  LSB  runs  in. 

Due  to  certain  implementation  screws  pertaining  to  remembering  that  a  particular  file  has  been 
loaded,  in  Lisp  implementations  with  p.ickagcs,  LSB  binds  the  package  to  the  user  package  when 
it  loads  a  system  definition  (or  Isbsystems)  file.  Lhis  provides  a  ihliiiill  for  the  package  Unit  file 
gets  loaded  into;  it  may  be  overridden,  if  necessary,  by  the  use  of  die  package  option  in  the  file 
property  list  (since  I  SM  system  definition  files  are  not  themselves  modules). 
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3.3  Relations  between  Systems 

The  most  significant  relation  between  systems  is  the  built-on  relation.  To  say  th.it  the  write 
system  is  bu/7/  on  iJic  loop  system  is  to  say  that  the  code  of  the  modules  of  ilie  write  system 
utilizes  public  facilities  of  the  loop  system.  The  built-on  relation  is  not  transitive;  tliat  is,  if  x  is 
built  on  y  and  y  is  built  on  z,  it  is  not  assumed  to  be  the  case  that  x  is  built  on  z.  Of  course, 
tlic  actual  dependencies  involved  depend  on  what  context  is  being  considered:  (.niupilation, 
interpretation,  or  mnning  compiled  code.  In  general  the  built -on  relation  is  viewcil  fiom  the 
context  of  compilation. 

If  tlie  built-on  relation  does  need  to  be  transitive,  that  information  may  be  gisen  to  1  SB  by 
the  use  of  the  users-implicitly-need  clause  in  place  of  tlic  built-on  clause.  I  he  use  of  this 
clause  in  the  system  definition  for  pretty -print -definition 

(define- system  pretty -print-definition 
(built-on  loop  {pdplO  user-hunk}) 

(users-implicitly-need  write) 

(modules  ppdef  ppdesc)) 

says  that  the  pretty-print-definition  system  is  built-on  the  write  system,  and  that  systems  which 
arc  built-on  the  pretty -print -definition  system  are  also  implicitly  built-on  the  write  system. 

Another  possible  relation  between  systems  is  sideways  extension.  For  system  hair  to  be  built- 
beside  of  system  kernel  means  that  hair  utilizes  the  facilities  of  kernel  just  the  same  os  if  it  were 
port  of  the  kernel  system,  but  implies  that  system  kernel  has  no  need  for  the  facilities  of  system 
hair.  Thus,  kernel  could  be  a  "core  system"  intended  for  extension,  and  hair  could  be  a  system 
which  docs  that  extending.  What  this  amounts  to  is  that  system  hair  utilizes  both  die  public  and 
system  information  derived  from  system  kernel. 


3.4  The  LSB  Proce.s.slng  Environment 

The  "environment"  which  TSB  establishes  for  tlie  processing  of  a  module  consists  of  three 
parts: 

simple  environmental  options 

These  include  such  things  as  the  package,  rcadtable,  and  input  radix.  All  of  these  map 
into  variable  bindings;  it  is  possible  to  bind  this  part  of  the  LSB  environment,  and  to 
calculate  what  it  should  be  without  actually  modifying  the  current  Lisp  environment. 

processing  support 

For  compilation,  this  is  typically  declarations  and  macro  definitions;  all  of  the  stuff 
obtained  by  loading  the  various  declaration  diversion  streams  of  tlic  systems  involved. 
For  interpretation,  this  is  whatever  the  module  or  its  system  says  needs  to  be  loaded  for 
interpretation;  usually  nothing,  as  I.SB’s  automatic  loading  is  oriented  solely  towards 
compilation  at  this  time. 

diversion  streams 

The  diversion  stream  definitions  for  the  module. 

I'hc  LSB  processing  environment  may  he  set  up  in  one  of  two  ways.  I  hc  most  common,  and 
the  only  one  av.nlable  outside  of  the  Lisp  Machine,  is  driven  entirely  by  the  macio  processing  of 
tlie  module  special  form.  First,  all  loading  necessary  is  |icrformcd;  the  proccssmy,  \iipi><<ri  above, 
riien,  all  of  the  environment  options  are  determined,  and  the  variables  arc  side  ellccted  to  tlicir 
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appropriate  values.  Finally  all  of  the  diversion  streams  appropriate  for  the  module  are  defined. 
(These  three  steps  are  presented  in  much  more  detail  in  section  3.4.6,  page  19.) 

On  the  Lisp  Machine  (or  in  any  Lisp  implementation  which  interprets  and  heeds  the  file 
property  list),  there  is  one  difference;  the  binding  environment  is  determined  at  the  time  the  file 
property  list  is  parsed,  and  so  is  csutblishcd  around  the  entire  loading  or  compiling  operation. 
Ihc  module  special  form  then  knows  not  to  bother.  One  uses  the  file  property  list  with  LSB  by 
using  the  LSB  option,  as  in 

:  Mode;  Lisp:  LSR -.module-name,  system-name 

Note  that  the  "arguments"  are  in  the  same  order  as  they  arc  to  the  module  special  form.  Use  of 
this  option  docs  not  obviate  the  need  for  the  module  special  form  at  the  beginning  of  the  file. 
Note  also  that  if  one  uses  the  LSB  system  definition  to  specify  the  package  a  file  should  be 
compiled  or  loaded  into,  it  is  necessary  to  use  this.  It  is  an  error  (which  will  have  unpredictable 
results)  to  specify  any  option  in  the  file  property  list  to  which  LSB  provides  a  default,  or  which  is 
itself  specified  in  the  system  definition.  All  such  options  which  LSB  handles  arc  enumerated 
below. 


3.4.1  Environment  Options 

input -radix  radix 

The  value  of  ibase  used  for  the  processing  of  the  module  will  be  radix.  The  default 
value  is  decimal. 

readtable  readtable-name 

llio  readtable  used  will  be  the  readtable  associated  with  readtable-name,  a  symbol; 
LSB  keyword  equality  is  used.  Tlic  default  used  is  the  name  standard,  which  is 
associated  with  the  readtable  current  when  LSB  was  loadcd/crcatcd.  There  arc  initially 
no  other  choices;  the  expectation  is  that  large  systems  with  special  input  syntax  will 
supply  special  readtablcs  of  their  own  (sec  section  12.3,  page  65). 

inclusion  -  test  -  readtable  readtable-name 

lliis  specifics  the  readtable  to  be  used  for  reading  in  inclusion  tests  (chapter  4,  page 
24).  readtable-name  may  be  unspecified  or  nil,  in  which  case  whatever  readtable  is 
current  at  the  point  of  the  conditional  inclusion  will  be  used;  this  is  tlie  default. 

package  package- name  pathname 

This  option,  which  is  ignored  in  Lisp  implementations  without  packages,  specifics  that 
die  package  to  be  used  should  be  the  package  assix;iatcd  with  package-name.  If  no 
such  package  is  defined,  then  a  file  is  searched  for  similarly  to  the  way  a  system 
tlcfinilion  is  .searched  for,  irsing  pathname  (which  is  optional)  as  a  default.  This,  in 
fact,  uses  tlic  same  search  list  which  searching  for  die  system  definition  docs.  'Lhe 
default  filename  looked  for  will  be  package-name,  and  the  default  file  tjpe  will  be 
pkg.  Also  looked  for  will  be  die  file  Isbpackages,  analogous  to  the  Isbsystems  file 
u.scd  for  system  definitions.  Of  course,  searching  is  less  likely  to  he  useful  in  this  case 
because  the  package  option  alre.idy  has  at  its  disposal  die  default  directory,  host,  and 
device  of  the  system  whose  definition  die  clause  appears  in.  It  is  unclear  at  this  time 
that  searching  is  an  appropriate  thing  to  do  anyway.  It  is  recommended  at  tins  time 
that  the  pat  k age  piiihname  he  given,  if  it  will  not  delimit  coireetly  tin-  first  time 
(iliiecior}  of  ill, It  givin  in  the  directory  chiusc  of  the  sy.slem  definition.  Jilenaine  of  the 
system  name,  etc.). 
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This  option  is  somewhat  special  for  two  reasons:  it  can  have  side-effects  during  its 
interpretation  (the  loading  of  the  file  and  creation  of  the  package),  and  it  also  does 
no!  provide  a  canonical  default  package  if  this  clause  is  not  given:  the  package  used 
in  the  absence  of  this  clause  would  be  just  that  used  if  LSB  were  not  present,  i.c.  one 
specified  in  tlie  file  property  list,  or  barring  that,  the  current  package. 

announce  kwd-l  kwd-2  ... 

Use  of  tliis  option  causes  tlie  module  special  form  to  produce  in  its  expansion  a  form 
which  will  "announce"  the  loading  of  that  module.  The  message  printed  will  contain 
the  module  name,  system  name,  and  the  name  of  the  source  file.  The  only  keyword 
implemented  at  this  time  is  version;  it  causes  the  version  of  the  source  file  to  be  put 
on  the  version  property  of  the  module  name.  This  hack  is  to  allow  the  announce 
option  to  supply  a  functionality  similar  to  that  of  the  Maclisp  herald  macro.  This 
functionality  fits  in  poorly  both  with  LSB  (since  only  the  module  name  is  used)  and 
with  non-Maclisp  Lisp  implementations,  because  of  packages;  outside  of  Maclisp, 
both  the  module  name  and  the  property  name  (version)  will  be  in  the  keyword 
package. 

do- macro -memoizing  how 

Controls  macro  memoization.  If  how  is  not  supplied,  the  default  is  assumed. 
Otherwise  how  may  be  t  for  the  default,  nil  for  none,  or  some  other  keyword 
describing  a  particular  mechanism  to  use.  For  full  details,  see  section  5.10,  page  39. 

type-check -visibility-classes  vis-class- 1 ... 

Routines  defined  with  the  named  visibility  classes  will  have  argument  type  checking 
code  automatically  generated  for  them.  This  augments  the  do-argument-type¬ 
checking  clause  (below),  and  is  discussed  more  fully  in  chapter  5. 

number-check-visibility-classes  vis-class-l ... 

Routines  and  macros  with  the  named  visibility  classes  will  have  number-of-argument 
checking  code  automatically  generated  for  them.  This  augments  the  do-argument- 
number-checking  clause  (below),  and  is  discussed  more  fully  in  chapter  5. 

The  following  options  are  all  "flag  options";  they  take  a  single  "argument"  which  is 
interpreted  only  as  being  t  or  nil.  If  the  argument  is  not  given,  t  is  assumed. 

do  -  argument  -  number  -checking 
do  -  argument  -  type  -checking 

Control  automatic  generation  of  number-of-argument  or  argument  type  checking  code, 
for  all  visibility  classes.  Obviously,  code  is  only  generated  when  it  is  actually  needed. 
Ihis  defaults  to  nil,  i.e.  no  checking  other  than  what  is  implicitly  supplied  by  the  Lisp 
definition  LSB  produces. 

needed  -  for  -  user  -  compilation 
needed  -  for  -  compilation 

I  hcse  have  to  do  with  specifying  whether  the  module  (or  all  of  the  modules  in  the 
system)  are  needed  for  tlie  compilation  of  systems  built  on  tliis  one.  I  hey  also  control 
the  rcdund.int  outputting  of  certain  definitions  (e.g.,  macros)  to  both  a  declaration 
diversion  stream  and  to  the  compiled  output  file.  This  is  currently  in  a  bad  state,  and 
is  being  rerised. 

inhibit -documentation -production 

Ibis  turns  oil  documentation  pnKluction.  When  one  has  source  code  which  runs  in 
multiple  I  isp  implement.ilions,  it  may  be  wasteful  for  each  implementation  to 
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redundantly  produce  the  same  documentation.  I'he  flag  this  sets  also  inhibits  the 
recording  of  information  used  fur  producing  automatic  documentation,  as  discussed  on 
page  56.  This  option  works  by  setting  a  flag  which  is  checked  by  the  lsb:divert- 
documentation?  function  (page  51),  which  is  a  default  diversion-stream  predicate  for 
documentation  diversion  streams.  Thus,  it  only  works  if  the  documentation  diversion 
streams  actually  use  that  function  for  their  diversion  predicate. 

3.4.2  The  Processing  Support  Options 

Here  are  the  system  definition  clauses  which  are  interpreted  for  various  reasons  such  as  setting 
up  the  compilation  environment.  Unlike  the  environment  option  and  diversion  stream  clauses, 
these  may  only  appear  at  top-level  in  the  system  definition,  not  in  a  module  specification  (a 
component  of  the  modules  clause,  below). 

built-on  system-spec- 1  system-spec-2 ... 

The  built -on  clause  specifics  that  this  system  is  built  on  each  of  the  other  systems 
specified. 

users-implicitly-need  sysiem-spec-l  system-spec-2 ... 

users- implicitly -need  is  like  built-on,  and  additionally  specifics  that  any  systems 
built  on  this  one  are  implicitly  built  on  all  of  the  systems  specified  here:  it  is 
transitive,  whereas  built -on  is  not. 

built-besfde  system-spec- f  system-spec-2 ... 
built-along-side-of ... 

Sideways  system  extension,  as  described  in  section  3.3,  page  13. 

files -needed -for -compilation  pathname-I  pathname-2 ... 

Ihc  named  files  will  be  loaded  in  during  compilation  environment  setup,  if  they  have 
not  been  already.  (Ihis  clause  used  to  be  named  additional-files-needed;  that  name 
is  accepted  as  a  synonym  for  files-needed-for-compilation,  but  that  synonymiration 
will  be  flushed  someday.) 

users-implicitly-need-files  pathname-l  pathname- 2 ... 

The  named  files  need  to  be  loaded  into  the  compilation  environment.  ITiis  need 
propagates  to  systems  built  on  this  one.  This  should  properly  be  named  users- 
implicitly-need -files -for -compilation  but  that  IS  quite  a  mouthful... 

modules  mndule-spcc- 1  module-spec-2 ... 

Specifics  the  modules  which  comprise  the  system.  A  module-spec  is  either  the  name  of 
a  module,  or  a  list  whose  car  is  tlie  module  name,  and  whose  edr  is  a  list  of  clauses 
similar  to  those  in  a  system  definition.  What  may  appear  there  is  described  in  section 
3.4.5.  page  18. 

default -user -options  opium-clause- 1  option-clause-2 ... 

Ihcse  specify  default  values  for  LSB  environment  options  (previous  section)  which 
should  be  used  for  systems  built  on  this  one.  The  defaulting  pr(x:ess  is  described  in 
section  3.4.6,  page  19. 
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3.4.3  The  Diversion  Stream  Clauses 

Diversion  stream  definition  clauses  allow  one  to  define  new  (or  redefine  existing)  diversion 
streams,  for  either  all  modules  in  a  system,  or  even  per-module.  In  this  way,  they  default 
similarly  to  other  LSB  options  discussed  above.  (Diversion  stream  definition  defaults  cannot  be 
inherited  from  systems  being  built- on,  however.)  A  list  of  the  keywords  used  for  defining 
diversion  streams  follows;  they  are  discussed  fully  in  chapter  8. 

diversion -stream  divstream-name  clause- 1  .  .  . 

form -diversion -stream  ... 

form-divstream  . . . 

declaration  -  diversion  -  stream 

declaration  -divstream 

dcl-divstream 

textual -diversion -stream  .  . . 
text-diversion-stream  . . . 
text-divstream  . . . 
documentation  -diversion  -stream 
doc -divstream 

3.4.4  Pathname  Specification  Clauses 

The  following  clauses  may  be  used  to  specify  default  pathname  components.  These  are  not 
only  accepted  in  the  system  definition,  but  also  within  a  module  spec,  and  in  various  other  places 
where  LSB  looks  for  pathnames,  such  as  in  diversion  stream  definitions. 

directory  subdir-I  subdirl ... 
dir  subdir-l  subdirl ... 

(directory  dir)  says  that  the  default  directory  to  use  is  dir.  In  most  cases  this  is  all 
that  is  needed,  since  typically  the  "canonicaT'  device  of  the  host  is  the  correct  choice, 
and  there  is  no  choice  of  host  in  most  Lisp  implementations.  If  multiple  subdirs  are 
specified,  then  they  specify  a  directory  hierarchy  path.  In  tlie  Multics  implementation 
of  LSB,  one  is  also  allowed  to  specify  the  entire  path  in  a  single  atom,  just  as  one 
would  for  the  Multics  Maclisp  namelist  format: 

(directory  >udd>Mathlab>LSB>format) 
is  equivalent  to 

(directory  udd  Mathlab  LSB  format) 

It  is  unfortunately  necessary  for  this  entire  path  to  be  specified. 

device  device-name 

For  whatever  it  is  worth,  this  may  be  specified.  For  example,  (device  arc).  This  is 
especially  useful  for  referencing  an  I  TS  machine  which  is  not  on  tlie  Chaos  network 
from  a  Lisp  Machine: 

( def ine-system  Brand-X 
(host  me) 

( device  ml ) 

(directory  brandx) 

.  •  •  ) 

host  host-name 

Specified  the  host  to  be  used.  This  is  obviously  only  useful  in  Lisp  implcni'.'ntaiions 
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which  as  a  matter  of  course  access  multiple  hosts,  namely  Lisp  Machine  Lisp.  It  will 
be  ignored  elsewhere. 

pathname  hosl-dependent- pathname 

This  clause  is  not  actually  a  system  definition  clause;  it  is  however  used  in  many 
places  in  conjunction  with  the  directory,  device,  and  host  clauses,  so  is  documented 
here  for  completeness.  It  is  used  in  places  where  a  complete  pathname  is  needed, 
and  will  have  its  missing  components  defaulted  from  the  other  three  clauses.  For 
example,  the  dumb -objects  system  is  defined  as  follows: 

( def i ne-sys tem  dumb-objects 
(directory  Isbl) 

(built-on  loop) 

(modules  (dumb-objects  (pathname  dumobj))) 

( needed -for- use r-compi 1 ati on ) ) 

Ihe  pathname  clause  shown  says  that  the  dumb-objects  module  has  a  filename  of 
dumobj  rather  than  the  default  (dumb-objects).  The  directory  is  defaulted  to  Isbl. 
If  that  particular  module  were  on  a  different  directory  (say,  test-dir),  the  modules 
clause  could  be  re-written  as  either 

(modules  (dumb-objects  (pathname  | test-di r ; dumobj | )) ) 

or  as 

(modules  (dumb-objects  (dir  test-dir)  (pathname  dumobj))) 
The  last  is  less  dependent  on  the  pathname  conventions  of  the  particular  host,  so  may 
be  a  reasonable  choice  if  the  pathname  components  will  be  the  same  for  different 
hosts  or  Lisp  implementations. 

3.4.5  The  Module  Specification 

A  module  specification  is  a  description  of  a  module  in  the  system.  It  may  be  either  just  the 
name  of  the  module,  as  in  the  system  definition  clause 
(modules  ppcode  ppdesc) 

or  a  list  whose  car  is  the  module  name,  and  whose  edr  is  a  list  of  clauses: 

(modules  (dumb-objects  (pathname  dumobj))) 

ITiesc  clauses  describe  various  attributes  about  the  module,  such  as  where  it  resides  in  the  file 
system  and  what  environmental  attributes  its  compilation  environment  should  have.  Most  of  these 
can.  in  fact,  be  defaulted:  the  name  of  the  file  (both  source  and  compiled  output)  defaults  to  the 
name  of  the  module,  with  the  directory,  device,  and  host  being  taken  from  those  defaults  for  the 
system  (as  cither  specified  with  the  corresponding  clauses  or  defaulted),  and  tlie  extension  or  file- 
type  for  the  source  and  compiled  output  default  to  whatever  is  appropriate  for  tlicm  in  the  Lisp 
implementation.  I'hcsc  can  he  selectively  overridden  by  use  of  the  pathname,  directory,  device, 
ind  host  clauses,  ;is  described  above.  Most  of  die  clauses  described  above  for  system  definitions 
arc  also  applicable  to  single  modules;  those  that  arc  not  arc  tliosc  which  describe  system  relations, 
listed  in  section  3.4.2.  ITius, 

(def 1 ne-sys tern  mathematical -hacks 
(built-on  loop) 

(modules  arithmetic 

( bi t-twiddi ing 

( input-rad  i x  fl ) ) ) ) 

describes  the  mathematical -hacks  system,  which  consists  of  the  two  modules  arithmetic  and  bit- 
twiddling.  Module  arithmetic  uses  an  input  radix  of  10  (decimal),  which  is  LSD's  default,  but 
module  bit -twiddling  uses  octal. 
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3.4.6  Environment  Setup  -  Details 

The  LSB  environment  setup  is  performed  in  one  of  two  ways.  In  general,  most  if  not  all  of 
the  work  will  be  performed  when  the  module  form  which  should  be  at  the  front  of  the  source 
file  is  processed,  cither  by  the  compiler  or  by  being  evaluated  during  loading.  In  both  cases  there 
are  three  fairly  discrete  actions; 

('0  Loading  whatever  support  code  is  needed  for  the  type  of  processing  being  performed, 
and  making  the  appropriate  declarations  (when  compiling) 

('2J  Establishing  the  binding  environment  (specified  with  the  various  options) 

fJJ  Defining  the  diversion  su'eams  which  will  be  used  by  that  module 

The  module  form  first  performs  step  /.  For  compilation,  this  involves  loading  all  of  the 
pubdcl  files  of  the  systems  this  system  is  built-on  (note  the  non-transitivity  of  the  built-on 
relation,  and  the  implications  of  the  users- implicitly -need  clause),  and  any  other  files  they  have 
specified  with  the  users-implicitly-need-files  clause.  Then  the  pubdcl  and  sysdcl  files  for  that 
system  itself  are  loaded.  I  his  is  a  depth-first  operation;  take,  for  example,  the  systems 
( de f i ne-sys tern  write 

(built-on  loop  Ibind) 

(modules  write)) 

(define-system  pretty-print-definition 
(built-on  loop  {pdplO  user-hunk}) 

( users - impl ici tly-need  write) 

(modules  ppdef  ppdesc)) 

(define-system  hacks 

(built-on  pretty-pr i nt-def i ni ti on ) 

(modules  crock  kludge)) 

If  we  arc  compiling  the  crock  module  of  the  hacks  system,  the  following  files  will  be  loaded 
(assuming  they  exist),  in  this  order; 
write  pubdcl 
ppdef  pubdcl 
ppdesc  pubdcl 
kludge  pubdcl 
kludge  sysdcl 

Additionally,  if  the  special  LSB  pre-processing  compiler  interface  is  no/  being  used  (see  section 
10.1,  page  59;  if  available,  this  is  the  default  action),  the  pubdcl,  sysdcl,  and  moddcl  files  of 

the  module  itself  will  be  loaded.  Note  that  by  default  there  is  no  moddcl  file  produced,  but  it  is 

provided  for  in  case  this  sort  of  forward-reference  capability  is  needed. 

Next,  the  binding  environment  is  set  up.  If  the  LSB  option  was  given  in  the  file  property  list 
of  the  source  file,  and  that  option  was  .actually  used  by  whatever  is  doing  die  processing  (e.g., 
load,  the  compiler),  then  tJiis  has  already  been  done.  It  is  expected  ifiat  environments  which  will 
be  using  this  will  have  the  support  necessary  already  loaded  (this  mainly  concerns  values  of 
defaulted  options,  or  new  option  definitions);  in  other  environments,  this  suppi  ct  should  have 
been  loaded  in  by  tbe  previous  step.  Ihis  also  is  why  the  Isb-load  (page  22)  function  exists— for 
the  loading  of  .in  interpreted  module,  tbe  variables  which  comprise  the  pr(x:essing  environment 
need  to  be  bouiul  so  th.it  the  module  form  does  not  side-circct  the  global  ernironment.  Anyw.iy, 

I  SB  sets  up  the  binding  environment  by  calculating  all  of  the  vaiiabics  which  will  be  aH'cctcd. 
and  then  filling  them  in  with  their  spetilied  values:  first  any  per-modulc  options  foi  the  module 
being  processed  are  looked  at.  then  any  for  the  system  as  a  whole.  Then,  any  options  specified 
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in  any  default -user -options  clauses  of  systems  this  one  is  built-on.  The  order  in  which  options 
are  defaulted  in  this  last  manner  is  not  extremely  well  defined  at  this  time,  but  it  can  be 
guaranteed  that,  when  built-on  relations  only  go  one-level  deep  (as  is  normal  unless  the  users- 
implicitly-need  clause  has  been  used  in  one  of  these  systems),  it  will  be  the  order  in  which  those 
systems  appear  in  the  system  definition.  Thus,  looking  at  the  write  system  definition  given  above, 
if  the  write  module  were  being  compiled,  first  any  default  user  options  of  the  loop  system  would 
be  looked  at,  then  those  for  Ibind.  Any  options  which  arc  not  cither  specified  or  defaulted  from 
other  systems  will  have  be  set  to  their  canonical  default  values. 

Lastly,  the  diversion  stream  environment  is  established.  This  may  implicitly  make  use  of 
support  loaded  during  step  /,  and  options  (variables)  set  up  by  step  2.  Essentially,  what  happens 
is 

(1)  All  extant  diversion  streams  arc  "killed",  if  necessary,  which  it  is  not  if  the  diversion 
stream  environment  is  "bound"  (as  done  by  Uic  Isb-load  function,  or  by  the  use  of 
LSB  in  the  file  property  list).  If  this  is  done,  a  warning  message  may  be  printed,  as 
this  could  in  theory  involve  closing  and  deleting  files  being  written.  But  normally 
nothing  interesting  is  happening  in  the  interpreter. 

(2)  All  diversion  stream  definitions  specified  for  the  module  only  arc  processed 

(3)  All  diversion  stream  definitions  given  at  top-level  in  the  system  definition,  which  have 
not  already  been  defined,  are  processed 

(4)  All  other  diversion  streams  which  LSB  uses  and  which  have  not  been  defined,  are,  using 
default  definitions  determined  from  the  type  of  processing  being  performed. 

Most  simple  systems  rely  solely  on  step  4. 

Finally,  the  module  form  macro-expands  into  various  potentially  interesting  things,  in  an 
implicit  progn.  Some  of  this  might  involve  bootstrap  code  (to  load  things  up);  this  has  not  been 
worked  out  yet.  Ihis  is  also  the  place  where  any  actions  dictated  by  the  announce  option  are 
performed.  And: 

•source-f  lie- Informat  ion  Variable 

i'hc  module  special  form  expands  producing  a  setq  of  this  variable  to  a  disembodied 
property  list  containing  much  infonnaiion  about  the  module.  (At  Uiis  time,  this  variable 
may  either  not  get  set  or  not  contain  much  inform.ition  v/hen  the  module  is  loaded 
interpretively.)  The  car  of  this  list  is  the  actual  real  pathname  (truename)  of  the  source 
file  (if  it  could  be  determined),  i'he  plisl  part  may  contain  the  following  properties: 

module 

Ihc  module  name.  In  Lisps  with  packages,  this  will  be  a  symbol  interned  in 
the  user  package.  It  will  be  all  in  one  case:  lower  on  Multics,  upper  elsewhere. 

:system 

Similar 

:lisp- version 

Ihc  version  number  of  the  Lisp  the  processing  was  performed  in.  I'his  will  be  a 
fixnum. 

:systom  version  info 

This  is  a  hairier  version  of  :lisp- version,  (hi  the  Lisp  Machine,  this  will  be  a 
string  which  is  Ihc  result  of  calling  si  system -version  info.  I'lsewhcrc.  I  SB 
will  make  do  witli  what  it  c.in  get.  but  in  .iny  case,  if  this  property  is  present. 
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it  will  be  a  string  (symbol,  in  PDF- 10  Maclisp)  containing  some  descriptive 
information.  Sec  si:system-version-info  and  related  topics  in  the  Lisp  Machine 
manual  for  more  information. 

:site  Some  name  for  the  machine  the  processing  was  performed  on.  Presently,  LSB 
only  knows  how  to  do  this  for  PDP-10  Maclisp.  On  Lisp  Machines,  it  is 
undecided  whether  this  will  be  only  the  Lisp  Machine  name  or  possibly  some 
composition  of  the  specific  Lisp  Machine  and  ils  site,  as  in  (MIT  CADR-6). 

:culprit 

ITic  name  of  the  user.  On  the  Lisp  Machine,  this  is  simply  the  value  of  user- 
id.  On  the  ITS  operating  system,  this  is  the  uname  rather  than  the  xuname  for 
reasons  having  to  do  with  INIT  files:  in  that  case,  the  xuname,  which 
supposedly  represents  the  real  user  name  as  opposed  to  some  instantiation  of  it, 
will  be  under  the  :claims-to-be  property. 

:claims-to-be 

On  U  S  only,  the  xuname  of  the  user,  if  it  differs  from  the  uname. 

;compiler- version 

Some  type  of  description  of  the  compiler  version.  This  is  a  brief  descriptive 
history  on  Multics.  On  the  PDP-10  this  will  simply  be  the  version  number  of 
the  compiler.  This  will  not  be  present  on  the  l.isp  Machine  because  the 
compiler  is  an  integral  part  of  die  basic  Lisp  Machine  system,  implicitly  included 
in  the  :lisp- version  and  :system- version -info  properties,  and  no  explicit 
infonnacion  is  available. 

:date  Date  and  time  of  the  processing,  in  the  form 

( {year  month  day)  hour  minute  second) 

The  year  is  excess*1900. 

LSB  also  handles  a  few  more  mundane  tilings  automatically.  When  setting  up  a  compilation 
environment  in  Maclisp,  a  genprefix  is  automatically  performed  on  the  concatentation  of  the 
system  name,  a  the  module  name,  and  a  c.g.,  "mysys.mymod-".  In  tlic  PDPIO 

Maclisp  implementation,  LSB  does  some  hackery  to  avoid  having  tlic  garbage  collector  thrash  due 
to  array  rckKation  during  compilation  environment  setup  (this  being  a  result  of  the  large  number 
of  arrays  used  by  fasloading  so  many  files).  If  one  has  a  system  which  causes  very  many  files  to 
be  loaded  and  this  seems  to  be  happening  (indicating  that  LSB's  default  handling  is  too  modest), 
a  (getsp  n)  clause  may  be  included  in  the  system  definition.  LSB  by  default  docs  this  with  n  of 
20000.  This  mechanism  may  be  improved  at  some  point.  Obviously  n  should  be  significantly 
smaller  than  tlic  amount  of  free  memory  remaining. 


3.5  The  LSB  Loader 

Because  of  the  possibility  of  an  interpreted  LSB  module  sidc-cffccling  the  environment,  which 
can  iKcur  in  I  isp  implemenlaiions  which  do  not  uiilire  the  file  property  list  or  if  the  module  docs 
not  use  the  LSB  option  in  the  file  property  list,  it  may  be  necessary  to  use  a  loading  function 
which  properly  scopes  all  of  the  LSB  environment  variables. 
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1sb-1oad  iHiihname  kwd-t  kwd-2  ...  kwd-n 

This  is  ihc  routine  LSB  uses  to  load  in  files.  It  causes  the  l.SU  environment  to  be  scoped 
around  the  loading;  all  of  the  flag  variables  arc  bound,  as  is  the  diversion  sucam 
environment.  Note  that  all  of  these  things  maintain  their  current  values;  if  the  file  being 
loaded  is  an  interpreted  1  SB  module,  it  is  the  module  form  in  that  file  which  will  reset 
them.  The  various  keywords  are  as  follows.  In  genera!  the  few  keywords  provided  negate 
default  actions. 

noerror 

Do  not  cause  an  error  if  the  file  is  not  found.  A  message  stating  this  may  be 
printed  depending  on  otlier  keywords  given;  in  any  case,  Isb-load  will  return 
nil. 

conditional 

If  this  file  has  been  loaded  already,  do  not  load  it  again.  Ihc  atom 
;previously- loaded  will  be  returned.  Note  that  in  die  1  isp  Machine 
implementation  this  atom  is  previously  -  loaded  in  the  user  (keyword) 
package,  but  in  Maclisp  it  is  an  atom  with  a  colon  as  its  first  character. 

nodefault 

Do  not  set  die  pathname  defaults  used  by  load  (and  Isb-load).  Normally, 
dicy  are  set  to  the  pathname  drat  gets  loaded.  Programs  that  call  Isb-load 
may  not  wish  to  change  the  default  pathname  on  die  user  without  his 
cogniiance,  in  which  case  dicy  should  use  diis  option. 

verbose 

Normally,  the  verbosity  of  Isb-load  defaults  to  die  value  of  *lsb- verbose?. 
This  explicitly  says  (hat  Isb-load  should  be  verbose. 

silent  I  hc  opposite  of  verbose. 

uninteresting 

This  is  primarily  useful  for  searching  for  a  file  to  load,  as  is  done  for  system 
.md  package  definitions.  Isb-load  will  not  modify  the  file  defaulis.  and  will 
not  error  out  if  die  file  is  not  found.  .Additionally,  it  will  not  even  print  an 
error  message  if  the  file  is  not  found;  however,  it  may  still  print  a  loading 
message  if  the  file  is  found,  dependent  on  the  presence  of  the  verbose  or 
silent  keywords,  or  the  value  of  *lsb  verbose?. 

Ihc  default  behaviour  of  Isb  load  is  for  it  to  follow  the  standard  system  load  function 
fairly  closely,  simply  augmenting  it  by  "scoping"  the  ISB  processing  environment 
appropriately. 

In  order  for  Isb  load  to  delemiinc  whether  some  file  h.is  .ilie.idv  been  lo.ided.  it 
iti.iinl.iins  a  d.il.ibase  about  lo.ided  files.  In  the  I  is|>  M.iehine  implement. ition,  such  a 
facility  alre.iily  exists,  so  Isb  load  uses  it;  elsewhere  there  is  none,  so  Isb  load  is 
incapable  of  determining  that  a  file  loaded  with  load  or  lasload  h.is  m  f.ict  been  lo.ided. 
In  the  common  cases  where  Isb  load  is  used,  such  .is  lo.iding  the  v.iiious  decl.iration  files 
into  ,1  compiler,  this  iioim.illv  iloes  not  matter.  I  he  Muliics  implement. iiimi  of  Isb  -load 
is  not  .ible  to  determine  th.ii  .i  more  recent  file  of  the  same  name  as  one  previously 
lo.ided  h.is  ih.inged. 
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In  the  Maclisp  implementation,  tsb-load  does  (sstatus  uuolinks)  after  loading,  to  avoid 
redefinition  problems.  It  is  not  yet  smart  enough  to  figure  out  if  it  needs  to  bind  fasload, 
however. 
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4.  Conditional  Inclusions 

Conditional  inclusions  allow  one  to  conditionally  include  portions  of  the  source  code  being 
processed.  This  may  be  done  by  die  use  of  reader  syntax  which  conditionali/cs  the  input  seen  by 
read,  or  by  the  use  of  conditionalization  macros  to  conditionalizc  code  being  compiled  or 
executed.  Ksscntially,  all  forms  of  conditional  inclusion  require  the  specification  of  an  inclusion 
lest.  An  inclusion  lest  may  be  one  of  the  following: 

nonnal  inclusion  test 

A  regular  inclusion  test  is  a  list  whose  car  is  an  atomic  symbol,  referred  to  as  the 
inclusion  tester.  ITie  inclusion  tester  is  examined  using  LSB  keyword  equality  to 
determine  how  the  form  should  be  interpreted  to  determine  success  or  failure  of  the 
inclusion  test. 

-  -  or  -  •  - 

An  inclusion  test  of  either  of  these  tokens  fails. 
atomic  symbol 

Any  other  atomic  symbol  used  as  an  inclusion  test  is  treated  as  being  shorthand  for 
(only-for  atomic- symbol). 

only-fop  Inclusion  Tester 

The  inclusion  test  (only-for  jc)  interprets  x  as  an  implementation  feature  test,  and 
succeeds  iff  that  test  succeeds.  An  implementation  feature  test  is  either  the  name  of  an 
implementation  feature,  or  a  logical  composition  of  implementation  feature  tests,  made 
with  and.  or.  and  not.  An  implementation  feature  name  is  tested  for  by  looking  in 
(status  features)  (but  note  also  section  4.2.  page  25);  LSB  token  equality  is  used. 
Multiple  ''arguments"  to  only-for  are  treated  as  an  implicit  or;  thus,  (only-for  Maclisp 
Lispm)  is  equivalent  to  (only-for  (or  Maclisp  Lispm)).  succeeding  if  cither  Maclisp  or 
Lispm  are  "features". 

except-for  Inclusion  Tester 

(except-for  //  i2  ...)  is  equivalent  to  (only-for  (and  (not  il)  (not  i2)  ...)).  ITius.  it  is 
die  complement  of  (only-for  il  i2  ...). 

A  mechanism  for  extending  the  composition  operators  for  implementation  feature  tests  is 
under  development. 

4.1  Read  Time  (  onditionaiization 

Read  time  conditionalization  is  effected  by  use  of  the  {  reader-macro,  'flic  general  fonnat  is 
{ inclusion- lest  anyihinyelsc-  with- matching-braces) 

Inclusion- test  is  rc.id  in  (by  calling  read)  and  interpreted  as  described  above.  If  the  test  fails, 
then  the  reader-macro  gobbles  down  all  of  the  text  up  to  the  matching  };  to  the  Lisp  reader,  the 
result  is  like  a  sp.icc  (i.c.,  an  atom  delimiter).  If  the  test  succeeds,  then  tlic  reader-macro 
immediately  returns,  leaving  anyihing-elsr-wiib-matching-braccs  intact  in  the  input  stream;  the  } 
will  behave  like  a  space  (an  atom  delimiter,  but  trthciwisc  ignored)  by  the  I  isp  re.idcr. 
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When  text  is  being  skipped  over  due  to  a  failing  inelusion  test,  matching  open-  and  close- 
braces  arc  kept  track  of.  There  is  no  way  to  "quote"  one  of  them  in  such  a  context;  what  one 

should  do  is  to  match  an  unmatched  brace  by  placing  it  in  a  comment  appropriate  for  the  syntax 

of  whatever  is  within  the  braces.  For  example, 

{(only-for  Lispm) 

:  Matching 

(princ  error-output) 

} 

Note  that  since  excluded  text  is  not  read  by  the  Lisp  reader,  it  need  not  be  syntactically  valid 

Lisp;  thus,  this  mechanism  is  good  for  conditionalizing  syntactic  constructions  which  arc  not  valid 

in  all  Lisp  implementations,  as  in 

(member  x  '{0  0.0  {Lispm  O.OsO})) 

where  O.OsO  is  "small-flonum"  zero,  a  syntax  not  supported  in  Maclisp.  And  of  course,  the 
excluded  text  may  be  used  as  comments,  by  using  cither  or  --  as  inclusion  tests; 

{-•-  Mode:Lisp;  PackagerPP  l-Apr-84 

This  file  defines  a  universal  pretty-printer 
with  capabilities  far  exceeding  any  thus-far 
elc} 

When  the  inclusion  test  is  read,  readtable  is  bound  to  the  readtable  specified  with  the 
inclusion-test-readtable  system  definition  option  (page  14).  If  nil  was  specified  as  the  readtable 
(which  is  the  default),  then  the  current  readtable  is  used.  This  option  exists  to  allow  nomial  Lisp 
syntax  to  be  used  (if  desired)  from  within  some  abnormal  syntax. 

4.2  Multiple  Contexts 

Thus  far,  the  test  for  an  implementation  feature  has  been  said  to  be  based  on  the 
membership  of  tlic  feature  name  in  (status  features).  This  is  not  strictly  true,  as  very  often  what 
is  intended  is  examination  of  the  target  environment  as  opposed  to  the  processing  (e.g. 
compilation)  environment.  The  inclusion  tester  only-for  and  except-for  arc  intended  to  refer  to 
tlic  target  environment,  which  is  normally  assumed  to  be  the  same  as  the  processing  environment. 
To  guarantee  that  the  test  is  based  on  the  processing  environment,  one  can  use: 

only-on  Inclusion  Tester 
except-on  Inclusion  Tester 

These  arc  tlic  same  as  only-for  and  except-for,  except  that  they  always  use  (status 
features),  guaranteeing  conditionalization  based  on  tlic  environment  in  which  the  test  is 
made.  Ihus, 

{(only-for  tops-20)  stuff) 

includes  stuff  if  the  code  is  intended  to  run  in  a  TOPS-20  Lisp,  whereas 
{(only-on  tops-20)  stuff) 

includes  stuff  only  when  it  is  being  read  into  a  ’TOPS-20  Lisp. 

There  is  currently  no  mechanism  for  specifying  multiple  "feature  environments".  Sec  section 
12.5.1.  page  67  for  a  description  of  the  current  facilities  which  may  be  used  to  implement  the 
above.  It  is  expected  to  change  drastically  when  a  better  facility  is  defined,  and  is  only  provided 
as  an  interim  solution. 
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5.  Defining  Operations 

For  the  purposes  of  discussion,  a  defined  object  which  is  either  a  routine  or  a  macro  will  be 
called  an  operation.  A  routine  is  one  where  the  body  of  code  in  the  definition  form  is  to  be 
executed  when  the  call  is  executed;  a  macro  is  one  where  the  body  of  code  is  to  be  executed  to 
produce  a  form  to  replace  the  call.  All  1.SB  operation  definition  foTns  have  the  same  general 
format: 

(define-  visclass-  definitiontype  prototype-call 

(declarations  del- clause- 1  dcl-clause-2  ...) 
fonn-l  form-2  .  .  .) 

where  visclass  is  the  visibility  class,  i.c.  public,  system,  or  private,  and  definitiontype  is  the  type 
of  definition,  e.g.  routine,  macro,  optimizer.  ITicre  may  be  any  number  of  declarations 
(abbreviated  dels)  forms,  but  they  must  precede  any  of  the  body  forms. 


5.1  The  Prototype  Call 

The  prototype  call  shows  what  a  call  to  a  routine  or  macro  looks  like,  defines  the  mapping 
from  the  arguments  into  the  formal  parameters,  and  specifics  the  data  types  of  both  the 
arguments  and  the  variables.  For  example. 

(frobnicate  foo  (optional  bar  ’ugh)  ( any-number-of  bietch)) 

.shows  a  prototype  cal)  for  frobnicate,  which  takes  one  required  argument,  one  optional  argument, 
and  any  number  of  other  arguments.  It  shows  how  the  call  is  to  be  mapped  into  the  formal 
parameters  of  frobnicate  (foo.  bar,  and  bletch);  the  first  argument  is  required,  and  maps  into 
the  foo  variable.  The  second  is  optional:  if  it  is  not  specified,  then  bar  will  be  bound  to  the 
symbol  ugh.  All  remaining  arguments  map  into  the  bletch  variable,  which  will  be  bound  to  a 
list  of  them.  This  prtKcss  of  mapping  from  the  arguments  into  die  forma!  parameters  is  known  as 
call  mapping,  and  the  keywords  such  as  optional  are  known  as  call  mapping  keywrds.  Other 
keywords  which  may  be  used  like  any-number-of  arc  one -or -more -of  and  two-or-more-of 
which  require  there  to  be  at  least  one  or  two  arguments  corresponding  to  that  formal  parameter, 
rest  and  body  are  synonymous  with  any-number-of;  the  latter  is  intended  for  macros  which 
take  any  number  of  forms  to  be  used  in  some  kind  of  implicit  progn.  If  there  is  a  minimum 
number  of  arguments  required  fur  diis  type  of  parameter  (a  rest  parameter),  it  is  meaningless  (and 
an  error)  to  have  any  optional  arguments.  There  may  only  be  one  rest  parameter,  and  it  must 
come  last 

One  can  also  specify  the  data  types  of  the  arguments  and  variables  in  the  prototype  call,  as  in 
the  example  shown  previously, 

( (In  r  1  ne  pub  I  i  c  rou  t  i  ne  (sqrt$  (flonum  n))  ...) 
lor  optional  and  rest  parameters,  note  Uiat  die  type  of  the  variable  and  the  type  of  the 
corresponding  arguincnt(s)  need  not  be  the  same.  One  can  thus  have; 

(my  -  rout i ne  (notype  (optional  (fixnum  count)  nil)) 

(vector  (any-number-of  (flonum  frobs)))) 
which  s.iys  that  my  routine  tikes  an  optional  argument,  count,  which  must  be  a  fixnum.  The 
variable  count,  however,  is  of  type  notype,  and  will  be  bound  to  nil  if  no  iirgnment  is  given. 
All  other  arguments  .uc  required  to  he  llonunis.  and  arc  gjithcred  into  ;i  vector  which  frob  is 
hound  to.  I  he  nil  shown  is  a  form  to  be  ev.ilu.iled  to  supply  .i  def.iiill  viiliie  (or  the  vtiii.iblo  if 
no  coiiespondmg  argument  is  present;  this  ev.ilu.ition  will  be  done  in  <in  environment  where  only 
the  v.iii.ibles  to  the  Iclt  m  the  prototype  call  have  been  hound  to  their  aigutuenis  or  def.iult 
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values.  In  this  instance,  that  nil  is  superfluous,  because  the  default  default  value  will  be  chosen 
on  the  basis  of  the  variable  type,  notype. 

The  optional  syntax  allows  for  the  specification  of  a  variable  to  be  used  as  a  flag  for  whether 
or  not  the  corresponding  argument  was  supplied; 

(frob-name  frob  (optional  new-name  nil  new-name-p ) ) 
which  could  be  ilic  prototype  call  for  the  routine  frob-name.  The  variable  new-name-p  will  be 
bound  to  t  if  frob-name  receives  two  arguments,  nil  if  it  receives  only  one.  ITiis  variable  is 
automatically  declared  to  be  of  type  truthvalue  (chapter  7). 

The  any -number -of  syntax  allows  for  the  specification  of  a  variable  to  receive  the  count  of 
the  arguments  which  were  mapped  into  the  formal  parameter: 

( def i ne-publ i c-routi ne  (average  ( one-or-more-of  numbers  count)) 
(quotient  (apply  (function  plus)  numbers)  count)) 

This  variable  is  automatically  declared  to  be  fixnum;  a  type  must  not  be  specified  for  it. 

Sometimes  an  operation  takes  an  argument  which  is  not  actually  used  by  the  code  of  the 
operation.  This  situation  typically  arises  when  the  code  is  not  totally  complete,  but  that  argument 
position  needs  to  be  "allocated"  for  future  compatibility.  Since  the  author  of  the  code  knows  of 
the  situation,  it  is  undesirable  to  have  the  compiler  warn  him  about  it.  One  may  use  the  unused 
keyword  to  tell  l.SB  that  the  variable  so  designated  does  not  get  referenced  by  the  code,  as  in 
this  prototype  call  for  hairy -routine: 

( hairy-routine 

f i le- to -be- processed 
file-to-send-output-to 
(optional  die-on-errors7) 

( any-number-of  (unused  keyworded-addi ti onal -opti ons ) ) ) 

I  his  option  is  applicable  in  all  l.SB  operation  definitions.  It  should  not  be  used  with  the  suppUed- 
p  variable  for  an  optional  argument,  nor  for  the  count  variable  for  a  rest  argument.  l.SB  will  do 
whatever  the  Lisp  implementation  requires  to  ensure  that  the  compiler  will  not  complain  about  a 
lack  of  reference  to  the  variable.  It  is  an  error  for  the  variable  to  be  referenced  in  the  code  of 
the  operation  when  the  unused  keyword  is  used. 

5.2  Variable  Bindings 

l.SB  operation  definition  forms  provide  syntax  for  binding  variables  within  the  body  of  the 
operation.  When  a  fonn  appearing  at  top  level  only  in  the  definition  body  su'iris  with  one  of  the 
keywords  auxiliary -bindings  or  bindq,  tlic  edr  of  that  fonn  specifies  a  binding  environment  to 
be  used  around  the  remainder  of  the  definition  form.  Some  may  find  this  syntax  distasteful  and 
prefer  to  use  a  fonn  which  textually  shows  the  binding  scoping  (such  as  Ibind  and  Ibind*);  others 
ni.iy  find  it  convenient  to  use,  as  it  allows  the  bindings  to  be  placed  more  naturally  while  not 
producing  deeply  nested  code.  Ibind  and  Ibind*  arc  macros  which  provide  similar  fiinctionality, 
but  without  restrictions  on  llieir  positioning;  lliey  arc  dtx:umeiucd  in  chapter  13.  page  73. 
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5.2.1  Auxiliary-bindings 

An  auxiliary -bindings  (abbreviated  as  either  aux- bindings  or  auxs)  form  binds  a  set  of 
variables  sequentially,  allowing  the  value  computed  for  one  to  depend  on  a  previous  variable. 
Tliis  form  looks  like 

(auxs  aux-bind-spec-I  aux-bind-spec-2  ...) 
where  each  aux-bind-spec  may  take  one  of  the  following  forms: 

variable 

The  variable  is  bound  to  nil. 

{variable  value) 

The  variable  is  bound  to  the  value  of  value. 

{{daia-type  variable)  value) 

The  variable  is  bound  to  the  value  of  value,  and  declared  to  be  of  type  data-lype. 
{variable) 

{{data-type  variable)) 

If  a  value  is  not  specified,  it  will  default  to  the  initial  value  for  the  stated  data  type. 
Thus,  the  body  of  the  code  in 

(define-public-routine  (frobnicate  x) 

(auxs  (a  (f  x))  ((fixnum  b))  ((flonum  c)  (g  a))) 
do-lhis 

(auxs  (p  (hack  a  b  c))) 
do- that ) 

produces  the  following  binding  contour: 

((lambda  (x) 

((lambda  (a) 

((lambda  (b) 

((lambda  (c) 
do- this 

((lambda  (p)  do-thal) 

(hack  a  b  c) ) ) 

(g  a))) 

0)) 

(f  X))) 

argument) 

along  with  ItKal  declarations  appropriate  for  die  I.isp  implementation.  There  is  actually  a  bit  of 
optimization  performed  to  try  to  bind  as  many  variables  in  parallel  as  possible;  this  is  done  for 
tlic  sake  of  Lisp  implementations  where  that  may  be  more  efficient,  especially  if  they  are  special. 
In  the  above  example,  b  would  be  bound  in  the  same  lambda  as  a,  since  it  is  being  bound  to  a 
constant. 
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5.2.2  Bindq 

bindq  is  an  alternative  to  auxiliary-bindings.  In  addition,  it  always  binds  variables  in 
parallel.  A  bindq  form  looks  like 

(bindq  varspec-l  value- !  varspec-2  value- 2  ...) 
and  can  be  used  in  the  same  places  as  an  auxiliary -bindings  form.  Each  varspec  may  be  either 
the  name  of  a  variable,  or  a  list  of  the  data-type  for  the  variable  and  the  name  of  the  variable. 
The  code  for 

( def i ne-publ i c-routine  (frobnicate  x) 

(bindq  a  (f  x)  (fixnum  b)  0  c  (g  x)) 
do-this 

(bindq  p  (hack  a  b  c)) 
do- that) 

produces  the  binding  contour 
( ( lambda  (x) 

( ( 1 ambda  (a  b  c) 
do-this 

( ( 1  ambda  ( p )  do-that) 

(hack  a  b  c))) 

(f  X)  0  (g  X))) 
argument) 

5.3  Defining  Routines 

def ine-publ Ic-routlne  (3  defpubr)  SpecialForm 
def Ine-system-routine  (3  defsysr)  SpecialForm 
def ine-private-routine  (5  defprivr)  SpecialForm 

In  LSB,  one  docs  not  define  ordinary  functions’,  one  defines  routines.  The  difference  is 
that  a  I.isp  function  definition  implies  a  specific  implementation,  whereas  an  LSB  routine 
definition  simply  says  how  one  desires  to  call  the  routine.  The  actual  implementation  of 
the  call  is  left  to  LSB,  and  may  differ  across  Lisp  implementations.  There  are  declaration 
options  to  give  LSB  information  which  may  be  useful  in  choosing  a  particular 
implementation,  and  to  demand  a  particular  one. 

Consider  the  following  routine  definition: 

(de fine-pub  lie-routine  ( print- decimal -number 

(number  n) 

(optional  stream)) 

(bindq  base  10.  *nopoint  t) 

(princ  number  stream)) 

The  functional  specification  of  print-decimal -number  ultimately  reduces  to  the  primitive  lambda 
expression  (lambda  (n  stream)  ...).  Somewhere  between  the  processing  of  a  call  such  as  (print- 
decimal -number  mini)  and  tlie  cvaluatitm  of  the  forms  in  the  definition  body  there  has  to  be  a 
mapping  made  between  the  call  and  the  application  of  that  primitive  lambda  expression.  One 
possiliilily  is  to  turn  the  call  (print-decimal  number  num)  into  a  new  c.ill  (print -decimal - 
number-aux  imm  nil),  with  print -decimal  numl)or-aux  defined  to  lake  the  same  arguinenis  as 
print  (fiu.imal  number,  exu  pt  (h.it  they  are  .ill  retjiiired,  I  SB  dtn's  in  fact  make  this  kind  of 
tr.inslbrm.iiion  in  I  isp  implemcni.itions  which  have  a  signific.mtly  less  cllieicnt  c.illing  sequ.'ncc  for 
ruiiclions  o(  a  v.ni.ihle  miiiiber  of  arguments. 
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The  prototype  call  for  a  routine  may  also  specify  tliat  the  argumcnt(s)  mapping  into  a  variable 
be  impliciily  quoted,  by  use  of  the  quoted  keyword  wrapper  around  the  variable,  as  in  the 
prototype  call 

(foo  (quoted  x)  (optional  (quoted  y)) 

( any-number-of  (quoted  frobs))) 

which  says  that  foo  takes  one  or  more  arguments,  and  none  of  them  are  evaluated.  This  implicit 
quoting  is  done  as  part  of  the  call  processing.  What  actually  happens  is  tliat  foo  is  defined  as  a 
macro  which  quotes  the  appropriate  arguments,  producing  a  call  to  foo-aux,  just  as  done  by  the 
optimization  for  routines  taking  a  variable  number  of  arguments  (in  fact,  both  of  these 
transformations  may  occur  at  the  same  time).  The  implication  of  this  is  that  it  is  not  possible  in 
general  to  apply  or  funcall  a  routine  which  takes  quoted  arguments,  lliis  restriction  is  based  on 
the  "lowest  common  denominator"  of  the  various  Lisp  implementations  LSB  is  aimed  at;  this 
restriction  may  be  lifted  at  some  point,  at  least  for  some  of  these  implementations. 

The  following  declaration  options  may  be  of  use  in  defining  routines; 

value-type  data- type- name 
data -type  data- type- name 

This  specifics  that  the  value  returned  by  the  routine  will  always  be  of  type  data-type- 
name.  If  the  type  and  the  Lisp  implementation  so  warrant,  this  may  produce 
appropriate  declarations  which  may  affect  the  calling  sequence  of  the  routine. 

do  -  arg  ument  -  type  -  checking  flag 

ITiis  turns  on  argument  type  checking  for  this  routine  if  flag  is  non-nil  or  unspecified, 
otherwise  turns  it  off.  Thus,  argument  type  checking  can  not  only  be  specified  per- 
modulc  or  per-system  (with  the  do -argument -type -checking  system  definition 
keyword),  but  also  per-definition. 

do  -  argument  -  number  -  checking  flag 

Like  do-argument-type-checking,  but  enables  or  disables  .number-of-argument 
checking  for  this  routine,  and  is  also  applicable  to  macros. 

type-check-arguments  var-l  var2 ... 

If  there  arc  no  vars  supplied,  this  is  equivalent  to  (do -argument -type -checking  t); 
otherwise,  it  enables  it  for  the  arguments  corresponding  to  only  tliosc  variables  named. 

returnable 

the  declaration  (returnable)  causes  the  entire  definition  body  to  be  fonned  inside  a 
prog,  with  a  return  wrapped  around  the  last  form.  This  is  convenient  firr  routines 
which  ordinarily  would  not  need  this  except  for  a  small  number  of  extraordinary  cases 
which  must  be  handled  specially  and  return  early,  (returnable  name)  causes  tlie  prog 
to  be  "named"  name,  so  that  it  may  be  explicitly  returned  from  (even  tlirough  other 
prog  or  do  forms)  b\  using  the  return- from  special  fomi,  as  in 
(def ine-publ ic-routine  (hack  1) 

(dels  (returnable  george)) 

(do  ( ( 11  1  (edr  11)))  ((null  11  )) 

(cond  ((not  (numberp  (car  11))) 

(  return  -  f  roin  george  ’error))) 

.  .  .) 

.  .  .  ) 

Since  naming  the  containing  prog  requires  the  Lisp  implementation  to  support  named 
/irogv,  this  extension  does  not  work  in  Maclisp. 
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Where  multiple  values  arc  supported.  LSB  uses  multiple-value-return  instead  of 
return,  and  multiple-value-return-from  instead  of  return-from  so  that  they  will  be 
passed  back  properly. 

default-definition -from  routine-name 

If  this  declaration  is  given,  there  should  be  no  "body"  for  the  routine,  'llic  definition, 
instead  of  being  created,  will  be  gotten  from  the  definition  of  routine-name,  which 
must  be  defined.  It  is  impemtive  that  the  prototype  call  and  declarations  for  this 
routine  reflect  those  with  which  routine-name  was  defined,  as  tliey  will  be  used  to 
produce  declarations  for  the  new  name.  This  option  should  not  be  used  lightly:  it  is 

designed  primarily  to  save  away  the  definition  of  an  existing  routine  so  that  that 

routine  may  be  redefined. 

redefinition 

This  exists  to  tell  LSB  tliat  the  routine  is  a  redefinition  of  some  existing  routine.  LSB 
will  try  to  keep  the  Lisp  and  compiler  from  complaining  about  the  redefinition.  Other 
than  tliat.  you  redefine  things  at  your  own  risk. 

primarily  -  applicable  -  routine 
applicable  -  routine  -only 

This  declaration  tells  LSB  that  the  routine  is  used  primarily  to  be  funcallcd  or 

applyed,  so  there  is  no  point  in  doing  sophisticated  call  processing  on  it.  Appropriate 
declarations  will  still  be  produced,  however.  It  is  illegal  to  have  quoted  arguments 
for  a  routine  with  this  declaration,  applicable -routine -only  is  the  old  name  for  this 
declaration;  it  should  not  be  used  in  new  programs,  as  it  will  be  recycled  to 

additionally  inhibit  diversion  of  declarations. 

slow -and -hairy 

Ihis  tells  LSB  that  the  routine  is  complex  enough  that  time  should  be  discounted 
when  a  space/time  tradeoff  is  made  for  deciding  what  (if  any)  calling  sequence 
optimizations  should  be  performed. 

perform  -  calling  -  sequence  -  optimizations 

■fells  I.SB  to  perform  calling  sequence  optimizations.  Useful  only  if  LSB's  default 
action  is  inappropriate. 

inhibit  -  calling  -sequence  -  optimizations 

inhibit-calling-sequence-optirnizations  is  exactly  the  opposite  of  perform -calling - 
seq uence  -  optimizations. 

implement-as  how  bvl 

This  requests  LSB  to  use  a  specific  implementation  for  the  routine  being  defined,  and 
supplies  it.  how  should  be  one  of  tlie  tokens  expr.  lexpr.  or  fexpr,  and  is  used  to 
make  the  appropriate  functional  declaration  for  the  routine.  Information  as  to  number 
of  arguments  and  the  argument  types  still  comes  from  tlic  prototype  call,  however  no 
automatic  aigumcnt  type  checking  or  number-of-argument  checking  will  be  performed. 

I  he  bound  variable  list  for  the  function  definition  will  be  bvl,  and  any  items  after  bvl 
in  tliis  declaration  form  will  be  prepended  to  tlic  body  of  the  definition. 

assembly  -  language  -definition 

If  this  is  present,  then  the  body  of  the  definition  is  assumed  to  consist  of  assembly 
langii.ige  code  (in  Lisp  form.it  .ippropri.ite  to  the  implementation)  rather  th.in  Lisp 
code.  I  SB  will  provide  the  .ippropri.ite  he.idcr  and  args  information  to  be  output, 
and  will  .lutomaiically  def.iult  the  declarations  which  would  otherwise  have  to  be 
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supplied  by  such  clauses  as  implement-as  and  inhibit-calling-sequence-operations. 
Use  of  assembly  code  in  this  fashion  keeps  ii  in  textual  proximity  to  the  "definition 
form”,  and  also  allows  LSB  to  continue  to  automatically  produce  declarations. 
Additionally,  any  pre-  and  post-definition  fonns  implicitly  generated  by  such  clauses  as 
redefinition  will  be  properly  placed  around  tiie  actual  definition.  For  an  example,  see 
page  42.  This  is  only  supported  in  POP- 10  Maclisp  at  present 

5.4  Open  Coding 

d«f  1n«-publ1c-open-codabla-rout1ne  (=  defpubopen)  SpecialForm 
def  1ne-system-open-codable-rout1ne' (=  defsysopen)  SpecialForm 
def Ine-private-open-codable-routine  (s  defprlvopen)  SpecialForm 

These  define  routines  just  like  define -v/sc/ass- routine,  and  in  addition  tell  LSB  that 
compiled  calls  to  such  a  routine  should  be  open-coded. 

open  coding  means  that  when  a  call  to  a  routine  is  compiled,  the  body  of  the  routine  will  be 
compiled  in  place  of  a  call  to  it.  Ibat  is,  if  we  have 

(def ine-pubi ic-open-codable-routine  (cube  (number  n)) 

(expt  n  3)) 
then  the  expression 

(plus  (f  x)  (cube  (g  x) ) ) 
will  be  compiled  as  if  it  were 

(plus  (f  X)  ((lambda  (n)  (expt  n  3))  (g  x))) 

The  routine  cube  wit!  be  defined  just  as  if  it  were  an  ordinary  routine,  except  that  no  calling 
sequence  optimizations  will  be  performed,  since  they  arc  obviated  by  the  open-coding. 

Defining  something  as  an  opcn-codablc  routine  has  some  advantages  over  defining  it  as  a 
macro.  First  and  foremost  is  tlic  clarity  of  the  definition.  Also,  the  routine  definition  typically 
uses  less  space  in  the  runtime  environment  than  a  corresponding  macro  definition  would.  An 
open-codablc-routine.  because  it  is  a  routine,  may  be  funcalled  or  applycd  if  there  are  no 
quoted  arguments  specified  in  the  prototype  call.  l.astly,  the  use  of  an  open-codablc-routine 
makes  the  visible  semantics  of  a  call  to  that  routine  obvious:  if  we  have 
(define -publ ic-open-codable-routine  (foo  a  b) 

(bar  b  a)) 

then  a  caller  of  foo  docs  not  have  to  worry  that  foo  will  evaluate  its  arguments  repeatedly  or  out 
of  order. 


•< 

t 

' « ' 


Obviously,  there  will  be  cases  where  it  is  not  necessary  to  bind  tJic  fonnal  parameters  of  an 
opcn-codablc-roiitinc  around  the  body  of  the  code.  Ihis  is  the  case  in  tlic  cube  example.  Rather 
than  piodiiving  (for  coiiipilalion)  an  expansion  like 
((lambda  (n)  (expt  n  3))  (f  x)) 
for  (cube  (f  x)).  it  is  obvious  that 
(expt  (f  x)  3) 

would  suffice,  for  any  function  (or  special-form  or  macro)  f.  LSB  has  two  mechanisms  to  handle 
this. 


riie  first,  used  l<\  dchuili.  is  htinhdo  i>ininii:<ilii>n.  I  sscnti.illy.  the  code  cxp.imled  to  be  used 
in  place  o(  the  original  c.cll  is  reexamined,  and  wherever  possible,  lambda-bindings  arc 
eliminated.  Ihis  succeeds  in  making  such  iraiisfonnalions  as  the  one  shown  above  for  cube.  LSI) 
knows  not  to  optimize  out  the  bindings  of  special  vari.iblcs. 
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The  second  is  to  explicitly  tell  LSB  that  the  arguments  to  the  routine  may  be  safely  textually 
substituted  into  the  body  of  tite  routine,  litis  is  done  by  means  of  the  use-sublis-for-open- 
coding  declaration.  Fur  example,  cube  could  hate  been  defined  as 

( def i ne-pubi i c-open-codable-rout i ne  (cube  (number  n)) 

(dels  (use-subl Is- for -open-coding) ) 

( expt  n  3 ) ) 

Obtiously  this  is  unsafe  and  mu  recommended  if  the  routine  references  the  variables  out  of  order 
or  anv  thing  but  exactly  once,  as  that  destroys  the  implied  semantics  of  function  calling.  And, 
since  sublis  is  actually  used,  tltcre  should  be  no  name  conflicts.  The  use  of  sublis  does  not  mean 
that  the  body  of  the  routine  may  be  a  pattern  to  be  substituted  into;  it  must  still  be  viable  as  an 
ordinary  routine.  I.SB  reserves  the  right  to  not  actually  use  sublis  if  it  can  preserve  the 
substitution  semantics  and  produce  better  code  in  some  other  manner. 

Opcn-codable-routines  may  be  defined  with  optional,  any- number -of,  and  quoted 
arguments.  Ihc  chocking  for  optional  arguments  will  be  performed  at  compile  time,  and  the 
argument  or  default  value  form  inserted  into  the  code  as  appropriate,  any-number-of  arguments 
work,  but  they  can  only  be  implemented  as  heap-consed  lists,  so  are  not  recommended:  often  in 
tills  case  a  macro  is  called  for,  or  perhaps  an  ordinary  routine. 

Occasionally  a  situation  arises  where  one  desires  to  have  a  routine  open-eoded  only  in  certain 
Lisp  implementations.  For  this,  one  may  give  an  ordinary  routine  definition  the  open-code 
declaration,  which  may  be  placed  inside  of  a  conditional  inclusion; 

( def 1 ne -pub  1 i c- rout i ne  (cube  (number  n)) 

{Lispm  (dels  (open-code))} 

( expt  n  3) ) 

which  causes  cube  to  be  open-coded  only  if  is  being  compiled  for  a  Lisp  Machine. 

A  note  is  in  order  with  respect  to  the  setf  special  form:  since  an  open-codablc-routine  is  not 
a  macro,  setf  cannot  determine  what  a  call  to  it  will  expand  to,  so  if  one  is  being  used  to  create 
a  synonym  for  some  sort  of  structure  reference  and  is  meant  to  be  invertablc  with  setf,  either 
setf  must  be  informed  how  to  make  its  transformation,  or  the  routine  should  be  defined  as  a 
macro.  Ihc  same  is  true  for  the  locf  special  form  in  Lisp  Machine  Lisp. 

5.5  Dcdning  Macros 

def  Ine-publ  1c-macro  (s  defpubmac)  Special  Form 
define-system-macro  (s  defsysmac)  Special  Form 
def  1ne-pr1vate-macro  (s  defprlvmac)  Special  Form 

Macro  definition  fomiat  in  LSB  is  similar  to  routine  definition  format.  The  same  call 
mapping  keywords  (e.g.  optional,  any-number-of)  may  be  used,  but  typed  and  implicitly 
quoted  arguments  may  not  be.  If  any  type  tif  rest  parameter  is  used,  no  implementation 
type  sluuild  be  specified  for  it.  as  the  variable  will  be  bound  to  a  sublist  of  Uic  original 
call. 

Ihus. 

( def i ne  pub  I ic-macro  (frob-name  frob) 

■ ( caddr  , frob  )  ) 

effectively  defines  frob-name  to  be  a  synonym  of  caddr.  Ibis  particular  example  is  defined  as  a 
macro  rather  than  as  .in  (ipen-codable-nuitine  so  that  the  setf  special  form  can  invert  it; 
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(self  (frob-name  x)  ’new-name) 

==>  (rplaca  (cddr  x)  ’new-name) 

The  flag  variable  which  may  be  specified  to  flag  whether  an  optional  argument  is  supplied  may 
be  usefiil  with  macros  as  well  as  with  routines; 

( def ine-publ ic-macro  (frob-name 

frob  (optional  val  nil  val?)) 

(cond  ((null  val?)  '(caddr  ,frob)) 

(t  '(rplaca  (cddr  .frob)  ,val)))) 

And,  of  course,  macros  arc  the  best  way  to  write  code  which  changes  environments  or  control 
flow: 

( def ine-publ ic-macro  (if  predicate  consequent 

{ any-number-of  else-forms)) 

(cond  ((null  else-forms) 

'(and  .predicate  .consequent)) 

(t  '(cond  (.predicate  .consequent) 

(t  .  .else-forms))))) 

(def ine-publ ic-macro  (using-decimal-radix  (body  body)) 

'((lambda  (base  •nopoint)  ,@body)  10.  t)) 


5.5.1  Un  needed  Macros 

Quite  often  one  needs  macros  around  in  the  runtime  environment  for  running  interpreted  code 
(which  may  or  may  not  be  in  the  same  module  a  macro  is  defined  in)  but  it  is  undesirable  for 
them  to  be  present  in  an  environment  where  all  of  die  code  is  compiled,  Tliis  is  often  necessary 
in  small  address-space  l.isps,  and  is  often  not  unreasonable  in  even  large  address-space  Lisps 
which  do  not  have  packages,  such  as  Multics  Maclisp,  to  avoid  cluttering  up  the  runtime 
environment  with  definitions  which  arc  only  needed  for  running  code  interpreted,  or  for 
debugging. 

def  1ne-pub1 1c-xmacro  (?  defpubxmac)  Special  Form 
def  1ne-system-xmacro  (=  defsysxmac)  Special  Form 
def  1ne-pr1vat0-xmacro  (h  defprivxmac)  Special  Form 

I'hc  only  difference  between  this  and  normal  macro  definition  (define- v/sc/ars- macro)  is 
th.it  the  (compiled)  macro  definition  will  be  sent  to  the  macros  diversion  stream  rather 
than  output  into  the  compilation  output  file.  The  utility  of  this  is  that  the  macros 
definitions  (which  arc  nonnallv  not  needed  if  all  callers  arc  compiled)  will  not  be  present 
in  the  compilation  output  file,  but  will  be  in  the  file  written  as  the  macros  diversion 
strc.im.  so  may  be  loaded  when  needed.  Ihis  type  of  macro  definition  is  common  in 
systems  which  define  many  (or  large)  macros  which  arc  not  normally  useti.  such  as  pretty- 
printers.  Note  that  the  semantics  of  this  depends  on  how  the  macros  diversion  stream 
bchavcs—scc  page  54. 
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5.6  Compiler  Macros 

Sometimes  one  wishes  to  define  something  as  a  routine  (for  efficiency  or  argument  checking 
when  it  is  called  from  interpreted  code,  or  for  its  ability  to  be  funcalled),  but  desires  special 
handling  of  a  call  to  it  when  it  is  compiled,  that  only  a  macro  can  provide.  Another  scenario  is 
where  one  is  defining  a  special  form  (section  5.7,  page  35),  and  it  is  imperative  to  have  special 
handling  of  the  form  when  it  is  being  compiled.  LSll  allows  one  to  define  macros  which  only  arc 
used  for  the  expansion  of  code  being  compiled. 

def1ne-pub1 1c-comp1 1e- time-macro  Special  Form 
def  Ine-system-compi  1e- time-macro  Special  Form 
deflne-prlvate- compile- time-macro  Special  Form 

Ihesc  have  syntax  identical  to  that  of  define -v/sc/uss- macro,  but  the  definition  is  only 
used  for  expanding  code  being  compiled. 

The  definition  of  cube  as  an  opcn-codablc-routine 

( def i ne-publ ic-open-codable-routine  (cube  (number  n)) 

(dels  (use-subl i s-for-open-codi ng ) ) 

( expt  n  3 ) ) 

is  performed  by  l.SB  just  as  if  the  user  had  done 

(def ine-publ ic-routine  (cube  (number  n)) 

(dels  ( inhibit-calling-sequence-optimizations)) 

( expt  n  3 ) ) 

( def i ne-publ i c-compi le-time-macro  (cube  n) 

(sublis  (list  (cons  'n  n))  ’(expt  n  3))) 

More  examples  are  given  with  the  descriptions  of  definition  constructs  which  may  also  require  the 
use  of  compile-timc-macros. 

Note  that  use  of  this  facility  may  compete  with  automatically  generated  code  for  calling 
sequence  optimi/atitin  or  open  coding;  if  this  is  suspected,  one  should  explicitly  disable  calling 
sequence  optimization  as  in  the  above  example,  by  use  of  die  inhibit-calling-sequence- 
optimization  declaration. 


5.7  Special  I'orms 

special  forms  arc  ciinslructs  which  do  strange  non-functional  tilings  with  their  arguments,  like 
eval  tJicm.  cond  is  a  special  form,  as  arc  do.  prog,  and  go.  In  most  cases  it  is  best  to  define 

special  constmets  like  this  as  macros,  so  that  only  one  definition  is  needed,  and  so  tfiat  code 

analyzers  (and  the  like)  need  not  understand  the  fonn  specially.  Ihus,  if  can  be  defined  as  a 
macro  as  it  is  on  page  .14.  There  may  be  situations  where  there  arc  overriding  reasons  for  using  a 

special  form  instead.  c\cn  considering  tlic  extra  effort  of  defining  a  compilc-timc-macro  so  that 

such  a  form  can  iic  properly  compiled.  One  possible  scenario  (in  fact,  the  one  which  led  to  the 
implementation  of  special  form  definition  in  LSI!)  is  a  system  (especially  in  a  limited  address 
space  l  isp)  where  there  arc  many  special  constmets  defined,  and  they  get  much  use.  The 
overhead  ol  exp.iiuling  and  rciTicmbering  all  of  those  macros,  combined  with  tlie  (xcasion.il 
tendency  of  macros  delmilions  to  take  up  more  space  than  ihc  corresponding  routine  definitions, 
may  be  just  too  large  a  price  to  pay. 
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def  Ine-publlc-speclal-form  (s  defpubspec)  Special  Form 

Only  public  special  form  definition  is  provided  for.  Automatic  type  checking  is  not 
handled  here.  Use  of  the  quoted  keyword  to  specify  implicit  quoting  of  arguments  is  an 
error;  all  arguments  are  implicitly  quoted.  (This  is  a  special  form,  after  all.) 

As  an  example,  we  can  define  if  as  a  special  form: 

( def 1 ne-publ i c-speci al -form  (if  predicate  consequent 

( any-number-of  else-forms)) 

(cond  ((eval  predicate)  (eval  consequent)) 

((null  else-forms)  nil) 

(t  (do  ((1  else-forms  (edr  1))) 

((null  (edr  1))  (eval  (car  1))) 

(eval  (car  1)))))) 

To  be  properly  compiled,  if  would  also  need  to  be  defined  as  a  compile-time-macro,  in  the  same 
way  it  is  defined  as  a  macro  on  page  34:  that  is,  simply  defined  with  define-public-compile- 
time-macro  instead  of  define-public-macro. 


5.8  Optimization  and  Transformation 

def  Ino-publ  1c-optim1zer  (=  defpubopt)  Special  Form 
define-system-optimizer  (5  defsysopt)  Special  Form 
def  Ine-prlvate-optlmizer  (=  defprivopt)  Special  Form 

An  optimizer  is  similar  to  a  compilc-time-macro  (section  5.6,  page  35),  and  additionally 
has  die  option  of  deciding  tiot  to  expand  the  call.  Although  the  specific  mechanism  used 
to  signify  that  the  optimizer  "did  nothing"  differs  in  differing  l.isp  implementations,  LSB 
optimizers  should  indicate  this  by  returning  nil;  if  nil  is  desired  as  the  actual  value, 
(quote  nil)  should  be  returned,  as  it  is  entirely  equivalent  in  any  context  the  optimization 
will  be  performed  in. 

When  the  compiler  compiles  a  call,  it  will  try  the  optimizers  for  tliat  call  before  it  tries  a 
macro  definition  (if  any).  Additionally,  l.SB  arranges  for  compile-time-macros  (and  thus  USB 
generated  calling  sequence  optimization  code)  to  come  last,  if  it  could  conllict  with  any  user- 
defined  optimizers  (since  compile-time-macros  and  calling  sequence  optimization  may  use  the 
optimizer  mechanism  to  do  their  work).  User  optimizers  will  get  tried  in  tlie  order  they  are 
defined  in. 

When  an  USB  routine  or  macro  is  defined,  code  is  generated  (as  part  of  the  declaration 
infonn.ition)  to  flush  any  existing  optimizers  and  compile-time-macros.  Thus,  optimizer  definitions 
should  come  after  the  routine  or  macro  definition  they  are  for.  and  they  should  appear  in  the 
same  file.  It  docs  not  work  to  mix  visibility  classes  either;  that  is.  if  the  routine  is  public,  it 
docs  not  necessarily  work  for  an  optimizer  to  be  private  or  system. 

Since  a  given  name  can  have  multiple  optimizers  associated  with  it,  it  is  helpful  for 
redefinition  purposes  to  associate  some  kind  of  identifier  with  each  particular  one.  This  should  be 
specified  in  the  identifier  (abbreviated  id)  declaration  clause; 

( dof ine-publ ic-opf imizer  ( f oo  argl  arg2) 

(dels  (id  nunibHi' ) ) 

(and  (niimberp  argl)  (numberp  argZ) 

'(super-foo  .(plus  argl  arg?)))) 

Ibis  identifier  should  be  a  syiubol,  and  need  only  be  unique  with  respect  to  the  opcr.ition  name 
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the  optimizer  lumdles.  It  is  highly  recommended  that  tlic  identifier  clause  be  used.  If  it  is  not 
used,  in  environments  such  as  l  isp  Machine  Lisp,  incremental  recompilation  of  an  optimizer  will 
not  properly  redefine  the  old  one. 

Optimizers  do  not  work  in  Multics  Maclisp.  Do  not  try  to  use  tlicm. 


5.9  Rc.st  Parameter  Implementation 

One  of  the  most  obvious  points  of  incompatibility  between  various  Lisp  dialects  is  the 
implementation  of  res/  pardme/ers.  LSB  attempts  to  compensate  for  this  by  providing  a  consistent 
and  safe  default,  and  by  allowing  explicit  .specification  of  how  the  data  object  the  formal 
parameter  is  bound  to  is  to  be  implemented. 

Die  default  implementation  of  a  rest  parameter  is  as  a  hcap-conscd  list:  a  list  is  a  simple  data 
representation  guaranteed  to  be  common  to  all  l  isp  implementations.  It  is  hcap-conscd  to  prevent 
obscure  and  erratic  behaviour  when  a  pointer  to  it  is  passed  up  outside  the  dynamic  scope  of  the 
function  call. 


nie  single  commivnality  between  Lisp  dialects  is  that  such  an  object  is  a  kind  of  sequence. 
Iliis  means  tliat  (in  theory  at  least)  one  should  be  able  to  access  components  of  the  object  by 
some  sort  of  indexing  routine.  One  may  thus  declare  in  the  prototype  call  that  the  variable  is  to 
be  implemented  as  a  sequence: 

(def ine -pub  1 ic -routine  (print- items 

(sequence  ( any-number-of  items  n))) 


( terpri  ) 

(do  ((1  0  (U  i)))  ((=  i  n)) 

(princ  (elt  items  i)))) 

where  elt  is  the  generic  sequence  accessor  (dcfitied  in  NIL.  but  not  in  Lisp  Machine  Lisp,  nor  by 
default  in  Maclisp).  This  particular  implementation  is  still  hcap-conscd.  however;  it  could  lead  to 
the  production  of  quantities  of  garbage  free  storage.  Since  most  of  the  time  one  uses  a  rest 
parameter  one  is  only  going  to  use  it  within  tlic  dynamic  scope  of  the  routine  it  is  a  parameter  of, 
it  is  w.Mcful  for  the  storage  used  to  hold  tliis  sequence  to  not  be  temporary,  rinis,  LSB  provides 
the  concept  of  tlic  argument -sequence  sequence  type  and  rest  parameter  implementation. 


The  argument -sequence  (abbreviated  argseq)  rest  parameter  implementation  causes  the  rest 
parameter  to  be  implemented  as  the  best  method  which  docs  not  consume  free  storage  provided 
by  the  l  isp  implementation.  Iherc  arc  mechanisms  dclincd  for  m.inipulating  tlicm,  which  map 
directly  into  the  methods  actually  used  in  the  Lisp  implementation.  What  happens  is  that  in  Lisp 
Machine  1  isp,  specifying  argument -sequence  is  like  specifying  pdl-list;  in  NIL,  it  is  like 
specifying  pdl-vector;  and  in  PDP-10  Maclisp,  the  variable  is  bound  to  a  fixnum  which 
incorpor.iies  the  information  which  is  implicitly  present  in  the  call  to  a  Icxpr,  and  also  acts  as  a 
fixnum  decl.iration. 


argref  nrg.vn/  index 

Mils  letches  the  wt/cuh  cicnicni  of  the  argiimcni-scqucncc  nrpsrif.  Index  is  zero-origined. 
In  I’DI’-ld  M.iclisp  this  is  almost  the  s.ime  as  a  call  to  the  arg  fiiiiclion;  in  lisp 
M.iclime  I  isp,  ii  is  the  same  as  ,i  siniil.ii  call  to  nth,  and  in  Nil  ,  it  liiriis  into  a  vref. 
In  all  implement. iiions,  this  will  be  inline-coded  when  compiled. 
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argstt  argseq  index  val 

I'his  clobbers  tlic  indexlh  element  of  the  argument-sequence  argseq  to  be  val.  In  all 
implementations,  this  will  be  inline-coded  when  compiled. 

argseq-length  argseq 

This  returns  the  length  of  the  argument-sequence  argseq.  Note  that  this  is  often  not 
necessary,  as  one  can  get  a  variable  bound  to  die  length  of  the  argument  sequence  in  the 
prototype  call.  This  will  be  inline-coded  in  all  implementations. 

argseq- 11  St  argseq 

Returns  the  elements  of  argseq.  in  a  list.  I'his  routine  is  noi  inline-coded,  and  its  use  is 
discouraged.  It  is  provided  so  that  orie  can  get  the  elements  out  of  an  argument-sequence, 
as  a  list;  this  is  primarily  for  debugging,  and  primarily  for  PDP-10  Maclisp,  where  an 
argument-sequence  is  implemented  as  a  data-type  which  docs  not  print  out  its  components. 

It  is  reasonable  to  declare  a  variable  which  is  not  a  rest  parameter  to  be  an  argument-sequence. 
Consider  the  following: 

( def ine-publ ic-routine  ( pr1 nt- i terns  (argseq  ( any-nomber-of  items))) 
( terpri ) 

( pri nt- i tems-aux  items)) 

(def  ine-pub} ic-routine  (prinl-items  (argseq  ( any-number-of  items))) 
( pri nt- i tems-aux  items)) 

( def ine-pri vate-routine  ( print-items-aux  (argseq  items)) 

(do  ((i  0  (1+  i))  (n  (argseq-length  items))) 

((=  i  n)) 

(print  (argref  items  i)) 

(princ  "  "))) 

I'or  use  with  the  loop  iteration  macro  (1  OOP],  I.SB  defines  the  argseq -elements  (aka  argseq- 
element)  sequence  iteration  path,  so  dial  one  may  iterate  over  the  elements  of  an  argument 
sequence  (or  some  subset  of  them): 

( def ine-private-routine  (print-items-aux  (argseq  items)) 

(loop  for  X  being  the  argseq-elements  of  items 
do  (prinl  x)  (princ  "  "))) 

In  I  isp  implementations  where  an  argument-sequence  is  a  kind  of  list  (l.isp  Machine  l.isp  and 
Multics  Maclisp),  the  argseq-elements  iteration  path  is  guaranteed  to  produce  just  a  simple 
iteration  over  the  list  in  simple  cases  like  the  above;  that  is.  in  these  cases  the  list  will  not  be 
repeatedly  indexed  into. 

For  those  who  know  what  they  arc  doing,  die  following  dala-typc  kcywurds  arc  recognized  as 
specifying  rest  parameter  implementations; 

argseq 

argument  -sequence 

I  his  is  as  described  above. 

list  A  heap-consed  ordinary  list.  In  the  1  isp  Machine  implementation,  diis  list  will  be 
made  with  all  die  elements  cdr-nexl  except  for  the  last,  which  will  be  cdr-normal 
rather  than  edr  nil-  this  i.s  piesiimed  to  be  a  reasonable  compromise. 

vector  A  he.ip  (.onsed  \cclor.  Ibis  evisis  primarily  for  Nil.. 

sequence 

A  heap  eonsed  sequence  of  the  type  appropri.ite  for  the  implementation;  equiv.iicnt  to 
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list  in  Maclisp  or  I.isp  Machine  Lisp,  vector  in  NIL. 

The  following  additional  implementations  exist,  but  are  less  general,  and  primarily  exist  for  one  to 
uke  advantage  of  particular  Lisp  implementation  features. 

pdl'list 

temporary -list 

This  says  to  implement  the  rest  parameter  as  a  stack-allocated  list.  This  is  only  truly 
possible  on  tlic  Lisp  Machine;  in  PDF- 10  Maclisp,  it  causes  explicit  reclamation  of 
the  list  on  normal  exit  of  the  routine,  and  elsewhere  is  equivalent  to  list. 

pdh  vector 

temporary -vector 

Ihe  rest  parameter  is  to  be  implemented  as  a  stack-allocated  vector.  This  is  only 
possible  in  NIL.  Klsewhcre  it  may  attempt  to  coerce  the  argument  sequence  into  a 
heap-consed  vector,  but  that  of  course  will  not  work  unless  there  is  vector  support. 

Of  course,  if  one  is  very  concerned  with  efficiency  and  needs  to  take  advantage  of  particular 
implementation  features,  one  can  always  specify  an  implementation-dependent  implement-as 
clause,  such  as  the  following  (for  the  Lisp  Machine): 

(def ine-publ ic-routine  (print-items  ( any-number-of  items)) 

(dels  (Implement-as  expr  (&rest  items))) 

(do  ((1  items  (eddr  1)))  ((null  1)) 

(print  (car  1))  (print  (cadr  ?)))) 

5.10  Macro  Memoization 

It  is  normally  the  case  that  any  particular  call  to  a  macro  will  expand  into  the  same  code.  It 
is  thus  a  significant  incfTicicncy  for  interpreted  macro  calls  to  be  repeatedly  expanded  every  time 
they  arc  evaluated.  I  hc  tenn  macro  memouation  refers  to  the  process  of  somehow  remembering 
the  expansion  of  a  particular  macro  call  so  tliat  it  docs  not  need  to  be  repeatedly  expanded. 

There  arc  various  mechanisms  for  accomplishing  this.  The  easiest  and  most  efficient  is  to 
simply  clobber  the  calling  form  with  die  expansion,  by  use  of  rplaca  and  rplacd.  Another  way  is 
to  clobber  the  form  with  another  macro  call  which  encodes  both  the  original  form  and  the 
expansion;  tliis  intermediate  macro  form  can  then  be  recognized  specially  by  pretty-printers,  which 
can  choose  to  show  cither  the  original  form  or  the  expansion.  If  additional  information  like  a 
definition  count  is  encoded,  then  the  clobbered  expansion  can  be  checked  for  validity  and  re- 
expanded  when  the  macro  is  redefined.  Yet  another  way  to  perfonn  macro  memoization  is  to 
store  the  expansion  in  a  hash  table;  this  has  the  advantage  of  not  modifying  the  call  at  all,  and 
also  not  showing  the  expansion  in  tlic  ctKle.  The  data  stored  in  the  hash  table  can  also  encode 
information  like  a  definition  count,  so  tliat  tlic  form  can  be  re-expanded  if  the  macro  definition 
has  changed. 

LSI!  supplies  three  methods  for  macro  memoization.  They  differ  in  the  code  which  will  be 
produced  in  tlic  m.icro  body;  any  particular  option  could  additionally  be  under  runtime  control. 
Ihe  method  chosen  m.iy  be  specified  with  the  do- macro -memoizing  clause,  either  in  a  system 
definition,  module  specification,  or  in  the  declarations  of  the  macro  itself. 

noni  If  the  "argument"  given  to  do  macro- memoizing  is  nil,  then  no  macro  memoization 
code  IS  piodiiced.  |■vcry  lime  a  call  to  such  a  macro  is  encountered,  the  expansion  will 
be  rc-compiitcd. 
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the  implemeniation  default 

This  is  the  default  used  by  LSB.  The  actual  method  used  varies  according  to  the  Lisp 
implementation;  the  intent  is  for  the  code  generated  in  the  macro  definition  to  be 
runnable  in  a  default  environment  of  that  Lisp  implementation. 

In  Multics  Maclisp,  code  is  generated  to  clobber  the  original  form  with  the  expansion  by 
use  of  rplaca  and  rplacd.  In  IJsp  Machine  Lisp,  the  displace  function  is  called  (q.v.). 
The  PDP-10  and  NIL  implementations  produce  slightly  more  complicated  code,  calling 
functions  which  allow  virtually  all  of  the  macro  memoizing  possibilities  described  above, 
under  runtime  control. 

displace 

This  may  be  specified  by  use  of  the  keyword  displace  as  the  "argument"  to  do -macro - 
memoizing.  The  code  generated  for  the  macro  definition  will  call  the  displace  function. 
Note  that  this  is  equivalent  to  the  (current!)  default  action  for  Lisp  Machine  Lisp.  If 
one  uses  this  in  Multics  Maclisp,  one  should  be  sure  that  a  displace  function  will  be 
available  at  runtime.  Again,  the  precise  runtime  semantics  of  this  depend  on  exactly 
what  displace  does. 

It  is  anticipated  that  a  mechanism  similar  (if  not  identical)  to  that  used  in  PDP-10  Maclisp 
and  NIL  will  be  implemented  for  Multics  Maclisp  and  Lisp  Machine  Lisp.  Even  if  not  supported 
by  the  Lisp  systems  tliemsclvcs.  it  would  be  usable  in  environments  where  it  could  be  ensured 
tliat  the  necessary  runtime  support  was  loaded,  and  may  aid  in  problems  evident  in  those  Lisp 
implementations  due  to  redefinition  of  macros  not  affecting  already-expanded  calls  to  those  macros. 

5.11  Forward  References 

dec!  are- routine  Special  Form 

{  decl  are-routi  ne  prototype-call 
del- clause- 1 
dcl-clause-2 
•••) 

produces  all  of  the  information  needed  to  compile  a  call  to  the  specified  routine,  in  the 
current  compilation  environment,  without  defining  the  routine.  This  is  not  needed  if  one 
is  using  tile  LSB  compiler  interface  (described  in  section  10.1,  page  59)  which  makes  a 
pass  over  the  file  extracting  all  infomtation  needed  for  compilation.  It  may  be  needed, 
however,  if  one  is  using  LSB  on  Multics  (which  docs  not  currcnily  support  the  LSB 
compiler  interface),  or  if  one  has  specifically  disabled  this  interface  in  the  P1)P-10 
implementation. 

Consider  two  routines  which  call  each  otlier: 

(def inepubl ic-routine  (foo  a  (optional  b  0)) 

(cond  ((zerop  b)  a) 

(t  (bar  (times  a  b)  (subl  b))))) 

( def i ne 'pubi i c - rout i ne  (bar  x  (optional  y  0)) 

( cond  ( ( zerop  y )  x ) 

( t  (foo  (plus  X  y  )  ( subl  y ) ) ) ) ) 

11  ilte  delimiion  of  bar  has  not  been  piocessed  when  loo  gets  compiled,  the  compiler  will  make 
ilel.itili  assumptions  about  bar  when  it  compiles  the  call  to  it.  Ihcsc  assumptions,  if  incorrect, 
could  make  the  e.ill  less  cllicieni;  they  might  e\en  make  the  compiler  error  out.  or  generate 
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incorrect  code. 

The  fix  for  this  example  is  to  put 

(declare-routine  (bar  x  (optional  y  0))) 
before  the  definition  for  foo.  LSB  will  extract  from  this  the  very  same  declaration  information 
which  it  extracts  from  the  definition  of  bar,  including  any  code  needed  to  perform  calling 
sequence  optimizations. 

A  declare-routine  fonn  should  be  constructed  from  the  same  prototype  call  and  declaration 
clauses  which  arc  used  in  defining  the  routine,  with  the  exception  of  any  declaration  clauses 
pertinent  only  to  real  definitions.  The  clauses  which  may  be  used  are  implement -as,  value -type, 
primarily-applicable-routine,  slow-and -hairy,  called- as -lexpr,  and  perform -calling- 
sequence-  optimizations. 

5.12  Dcfinitionlcss  Routine  Definitions 

Sometimes  one  would  like  to  use  LSB  to  propagate  declaration  information  about  a  routine, 
but  cither  the  routine  is  defined  elsewhere  (possibly  without  LSB)  or  it  is  not  defined  in  Lisp. 
For  this,  one  can  simply  omit  the  body  of  the  definition.  It  is  the  responsibility  of  the  user  to 
ensure  that  the  calling  sequence  LSB  determines  for  the  routine  to  in  fact  be  identical  to  what  it 
actually  is,  by  use  of  the  appropriate  declarations.  For  example,  the  following  defines  for  the 
PDF- 10  a  flonum-only  +  hinction  which  checks  for  overflow: 

(define-public-routine  (f+  (flonum  x)  (flonum  y)) 

(dels  (value-type  flonum)  ( implement-as  expr)) 

) 

( lap-a- 1  i St 

'((lap  f+  subr ) 

(args  f+  (nil  .  2)) 

(push  p  (%  0  0  floatl)) 

(move  tt  0  a) 

(jrst  2  @  (%  0  0  foo)) 
foo  (fadr  tt  0  b) 

(jsp  f  (•  1)) 

(tlnn  f  40000)  :  this  is  octal 
(popj  p) 

(lerr  0  (%  sixbit  | FLOATING-POINT  OVERFLOW! |)) 
nil)) 

Actually,  this  example  is  simple  enough  that  it  would  be  best  written  with  the  assembly- 
language-definition  clause,  as  follows: 
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( def ine-publ ic-routine  (f+  (flonum  x)  (flonum  y)) 

(dels  (value-type  flonum)  ( assembly-1 anguage-def i ni tion) ) 

(push  p  (%  0  0  floatl)) 

(move  tt  0  a) 

(jrst  2  0  (%  0  0  foo)) 
foo  (fadr  tt  0  b) 

(jsp  f  (•  1)) 

(tlnn  f  40000)  ;  this  is  octal 
(popj  p) 

(lerr  0  (%  sixbit  | FLOATING-POINT  OVERFLOW! | )) ) 

Of  course,  not  all  such  cases  are  this  simple,  and  it  may  not  be  possible  to  share  code  between 
various  routines  when  the  assembly  code  for  them  is  in  separate  LSB  definition  forms. 

5.13  DcHning  Functional  Properties 

Very  often  it  is  necessary  to  put  a  "function"  on  some  property  of  a  symbol.  Lisp  has  the 
syntax 

(defun  (foo  propname)  (this  that)  ...) 
such  that  one  may  do 

(funcall  (get  'foo  ’propname)  this  that) 
in  order  to  invoke  this  function.  LSB  supports  a  similar  syntactic  construct 

For  routines,  one  may  simply  use  a  list  of  the  symbol  and  the  property  in  place  of  the  name 
of  the  routine,  as  in 

( def ine-publ ic-routine  ((foo  propname)  this  that)  ...) 
which  is  the  LSB  way  of  doing  the  previous  example.  Although  it  may  seem  that  there  is  no  call 
for  a  visibility  class  in  such  a  definition,  tlicrc  is:  such  a  definition  might  need  to  be 
documented,  and  a  visibility  class  is  needed  to  determine  where  the  documentation  may  need  to 
be  sent  to.  There  is  unfortunately  no  mechanism  for  remembering  this  information  at  this  time, 
however,  so  one  should  not  attempt  to  use  document- routine  (page  55)  on  such  a  thing. 

For  such  a  definition,  LSB  automatically  inhibits  declaration  production  and  calling-sequence 
optimizations. 

In  PDF- 10  Maclisp,  one  may  also  use  the  "three-list”  format: 

( def 1 ne-publ i c-rout i ne  ((foo  hackexpr  hacksubr)  a  b)  ...) 
being  essentially  the  same  as 

(defun  (foo  hackexpr  hacksubr)  (a  b)  ...) 
which  puts  the  interpreted  definition  on  the  hackexpr  property,  but  the  compiled  subr  pointer  on 
the  hacksubr  property. 

If  one  considers  macros  to  be  simply  a  way  to  perfonn  a  mapping  from  one  call-like  form  to 
some  other  form,  ilien  this  extension  is  applicable  to  them  also. 

( def ine-publ ic-macro  ((foo  frobnicate)  x  y) 

(list  'cons  X  y ) ) 

puts  a  function  on  the  frobnicate  property  of  foo  such  tliat 

(funcall  (get  ’foo  ’frobnicate)  ’(foo  1  2)) 

=>  (cons  1  2) 

Macro  memoi/ation  (section  5.10.  page  .V))  is  turned  off  by  default  for  this  type  of  construct 
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ITie  syntax  for  this  is  both  cumbersome  and  moderately  unaesthetic.  It  is  expected,  however, 
that  such  constructs  will  rarely  be  written  out,  but  rather  constructed  by  macros  which  can  hide 
the  property-list  implementation: 

( def i ne-system-macro  ( def ine-frobnicator  name  bvl  (body  forms)) 

' ( def i ne-pri vate-routi ne  ((,name  frobnicator)  ,@bv1) 

(dels  ( al so-needed-for  public-compilation)) 

, ©forms) ) 

5.14  Prototype  Call  Summary 

A  variable  specification  in  a  prototype  call  has  the  full  form  shown  below. 

varspec  :  :  =  simple-mrspec  \  opiional-vanpec  \  rest-varspec 

simple- vanpec  ::=  typed- variable  (  (quoted  typed- variable) 

(  (unused  typed- variable)  |  (unused  (quoted  typed- variable)) 

I  (quoted  (unused  typed- variable)) 

I’he  quoted  option  may  only  be  used  with  routines,  and  is  described  on  page  30.  The 
unused  is  applicable  to  any  type  of  1.SB  operation  definition,  and  is  described  on  page  27.  If 
a  simple-varspec  appears  in  a  prototype  call  to  the  right  of  an  oplional-varspec ,  it  is  interpreted 
as  if  it  were  (optional  simple-varspec). 

typed- variable  ;  ;  =  variable- name  \  {data- type- kwd  variable- name) 

All  pre-defined  data  type  keywords  arc  enumerated  in  chapter  7,  page  47. 

oplional-varspec  :  :  - 

simple-aptional-varspec  |  (data- type- kwd  simple-optional-varspec) 

simple-oplional-varspec  :  :  = 

(optional  simple-  variable ) 

I  (optional  simple-  variable  default-  value- form ) 

I  (optional  simple- value  default- value- form  variable- name) 

The  uses  of  default-value-form  and  variable-name  are  explained  in  section  5.1,  page  26. 

rest-varspec  :  :  = 

simple- rest- varspec  (  (rest-variable-implementalion-lype  simple-resl-varspec) 

simple- rest- varspec 

( rest-varspec- kwd  simple-variable) 

I  (rest-varspec- kwd  simple- variable  variable- name) 

Itic  specifics  of  the  optit)nal  variable- name  arc  discussed  in  section  5.1,  page  26. 

rest- varspec- kwd  =  a  rcst-iniplcincntation  keyword 

I  hese  arc  full>  discussed  in  section  5.9.  page  37. 
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rest- variable- implementation' type  : :  =■ 

any-number-of  |  one-or-more-of  j  two-or-mora-of  |  body  |  rest 
The  specific  keyword  used  implies  the  minimum  and  maximum  number  of  arguments  which 
are  to  be  mapped  into  the  particular  rest-variable.  There  are  none  currently  defined  which 
specify  a  maximum,  one-or-more-of  and  two-or-more-of  specify  one  or  two  arguments  as 
a  minimum;  any-number-of,  body,  and  rest  have  no  restriction. 


U 


I 
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6.  Defining  Variables 

An  LSB  \ariablc  definition  allows  for  all  declaration  and  initialization  information  normally 
needed.  The  definition  form  thus  provides  a  distinct  locus  in  the  source  text  for  that  information 
and  the  diKumcntation.  Defining  a  variable  constitutes  declaring  it  to  be  special',  the  specification 
of  type  information  for  variables  which  arc  not  special  (i.e.,  local  or  lexical  variables)  is  handled 
by  the  constaicts  with  which  the  binding  is  specified,  as  discussed  in  the  previous  chapter,  and 
chapter  13. 

def  Ine-publ  1c-var1ab1e  (3  defpubvar)  Special  Form 
defina-system-var  labia  (3  dafsysvar)  Special  Form 
daf  1na-pr1vata-var1ab1a  (s  dafprivar)  SpecialForm 

rhese  are  the  special  forms  with  which  one  defines  variables.  As  with  all  LSB  definition 
forms,  tlicy  should  only  appear  "at  top  level"  in  a  module,  to  be  processed  by  the 
compiler  or  interpreter. 

The  general  format  of  variable  definition  forms  is 
(define-  visclass-  variable  variable- name 
clause- 1 
clause- 2 

...) 

as  in 

{ def ine-public-vari able  •maximum- 1 i ne- length 
(value-type  fixnum) 

( def aul t- i ni t  78)) 

which  declares  'maximum -line-length  to  be  special,  says  its  value  is  always  fixnum,  and  will 
initialize  it  to  78  if  it  is  docs  not  already  have  a  value. 

Ihe  clauses  which  mo.  be  supplied  in  addition  to  the  common  definition  clauses  (section  2.6, 
page  8)  are: 

value-type  (ype-name 
data -type  type- name 

Asserts  that  the  value  of  the  variable  is  always  of  this  type.  Appropriate  type 
declarations  may  be  produced  if  warranted  in  the  Lisp  implementation. 

initialization  initializaiion-form 
init  iniiializaiion-fonn 

When  the  module  is  loaded,  the  variable  will  be  unconditionally  initialized  to  the 
value  of  iniiialization-form. 

default  -  initialization  initialization-form 
default -init  iniiializalion-form 

Like  the  initialization  clause,  but  only  sets  the  variable  if  it  is  not  already  valued. 

divert -reinitialization -to  tlivstrcam-l  divstream-2 ... 
divert -reinit- to  divsncam-l  dirsiream-2 ... 

Ihis  clause  causes  a  setq  fonn  of  the  variable  to  its  initialization  to  be  oulpul  to  each 
of  the  named  diversion  streams.  It  thus  may  only  be  specified  if  cither  the 
inlliulizatioii  or  dc'fault- initialization  clauses  arc  given.  Note  that  tlic  reiniti.ili/.ition  is 
alw.ivs  uncoiulition.il.  This  can  be  used  to  produce  a  file  which  when  loaded  will 
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reset  a  collection  of  variables  to  their  initial  states. 

also-divert-reinitialization-to  divstream-I  ... 
also-divert-reinit-to  divstream-I ... 

Mthough  this  probably  is  not  needed  because  there  arc  no  default  reinitialization 
diversions,  it  is  included  for  uniformity.  It  could  conceivably  be  of  use  if  one  had  a 
macro  which  produced  an  LSB  variable  definition  which  provided  for  reinitialization 
diversion  and  also  passed  along  declaration  clauses. 

The  LSB  variable  definition  facility  may  also  be  used  purely  for  declaration  purposes.  This  is 
useful  in  cases  where  either  forward  references  occur  (but  see  section  10.1,  page  59),  or  where  the 
variable  is  not  really  a  part  of  the  module  but  still  needs  to  be  declared  for  some  reason. 

daclare-varlable  SpecialForm 

This  is  a  variant  of  the  variable  definition  special  forms  which  can  be  used  for 
implementation- independent  declaration  purposes.  It  only  accepts  the  value-type 
declaration  clause,  as  none  of  the  others  are  applicable. 

Kxample: 

{ dec! are-var i abl 0  *count* 

(value-type  fixnum)) 
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7.  Data  Types 

l-SB  provides  a  scheme  whereby  one  may  symbolically  specify  the  data  type  of  something. 
This  data  type  is  used  to  provide  variable  and  function  value  declarations  (when  appropriate  to 
the  Lisp  implementation)  and  also  to  default  tlic  initial  values  of  bound  variables  and  unspecified 
optional  argumenLs,  It  is  also  used  to  provide  automated  type  checking  for  arguments. 

Here  arc  the  data  type  keywords  which  LSD  defines  initially, 
notype 

This  essentially  means  "untyped".  This  is  what  you  get  when  no  data  type  keyword  is 
specified,  and  there  is-  no  default  for  the  particular  context. 

fixnum  A  limited-precision  integer. 

integer 

Any  si/.c  integer. 

number 

Any  number. 

flonum 

A  flonum.  This  in  general  corresponds  to  the  Lisp  object  with  typep  of  flonum. 
small -flonum 

Similar  to  flonum.  This  exists  only  in  Lisp  implementations  which  have  such  a  data¬ 
type,  such  as  f.isp  Machine  Lisp. 

character -code 

In  practice,  this  is  equivalent  to  fixnum.  In  theory,  it  might  cause  special  storage 
strategics  to  be  used  because  of  the  limited  range. 

truthvalue 

In  practice,  this  is  tltc  same  as  notype.  In  theory,  it  might  be  used  to  optimize 
rciurned-valucs  of  conditionals  (and  the  like).  It  essentially  states  that  only  the  t-or- 
nil-ncss  of  tlic  value  is  of  interest. 


argseq 

argument -sequence 
list 

temporary -list 

pdl-list 

vector 

temporary -vector 

pdl-vector 

sequence 

These  data  type  keywords  arc  all  specially  recognized  as  specifying  the  implementation 
of  real  parameters.  T  his  is  fully  discussed  in  section  5.9,  page  37. 
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7.1  Defining  Data  Types 

One  may  define  a  data-lype  keyword  to  1.SB  in  terms  of  an  already  defined  type  it  is  a 
specialization  of. 

def  1ne-pub1  ic -data- type  Special  Form 
define -system-data- type  Special  Form 
def  1ne-pr1vate-data-type  Special  Form 

(  def  ine-publ  ic-data-type  data-type-keyword 
clause- 1 
clause-2 
...) 

defines  data-type-keyword  to  LSB.  The  information  is  declared  in  the  current  environment, 
in  the  compiled  output  file,  and  in  the  declaration  file  appropriate  for  the  visibility  class. 
All  the  normal  definition  keywords  may  be  used  in  the  clauses.  One  may  additionally  use 
the  following  clauses; 

continue-with  data-type-keyword 

This  says  wc  should  get  other  information  from  the  data-type-keyword  data¬ 
type.  This  defaults  to  notype. 

predicate  routine-name 

This  says  that  routine-name  is  a  predicate  of  one  argument  which  defines  this 
dau-type. 

initial -value  initial- value 

Specifics  the  default  initial  value  to  be  used  for  this  data-type. 

For  example,  tlie  Brand-X  system  defines  the  following  data-types; 

(def ine-publ ic-data-type  Brand-X-object 
(predicate  Brand-X-objectp) ) 

( def i ne-pub 1 i c -data- type  triple 
(predicate  triplep) 

(continue-with  Brand-X-object)) 

F.ieli  data-type  which  has  a  predicate  assixiated  with  it  can  also  have  automatic  argument  type 
checking  performed  for  an  argument  of  that  type.  When  one  defines  a  daU'i-typc,  the  code  to  do 
this  is  automatically  generated.  The  way  in  which  this  is  done  varies  in  ditferent  Lisp 
implemcnt.itions;  in  Maclisp,  tiic  (output  from)  define -i7.vc4/5.v- data -type  is  needed  for  this 
argument  checking  to  be  performed,  hut  on  tlie  I  isp  M.ichinc  it  is  not  (although  the  predicate  is 
if  it  will  not  he  open-errded),  l  or  example.  Brand  X  gels  automatic  type  checking  for  the 
argument  given  to  the  ilk  routine,  wliich  is  defined; 

(define  publicroiit,  ino  (ilk  (triple  x)) 

(dels  ( check  - args  ) ) 

.  .  .  ) 
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8.  Diversion  Streams 

Diversion  streams  are  used  by  I.SB  to  implement  derivabiliiy  (section  2.1).  They  can  be 
loosely  divided  into  two  categories,  depending  on  the  kinds  of  objects  and  operations  they  handle: 
form  diversion  streams,  which  arc  used  generally  for  Lisp  code  or  forms,  and  textual  diversion 
streams,  which  handle  text.  Within  each  of  these  broad  divisions  there  arc  various  additional 
types  which  determine  how  the  diversions  arc  to  take  place,  and  the  transformations  to  be  made 
on  the  objects  diverted.  For  example,  a  declaration  diversion  stream  is  intended  to  divert 
declarations— 'hai  is,  forms  to  be  executed  and  operations  to  be  defined,  to  tell  the  compiler  how 
to  compile  things,  fhe  forms  diverted  to  a  declaration  diversion  stream  will  be  compiled  into  a 
file.  A  form  diversion  stream  is  similar,  but  does  not  imply  that  the  contents  arc  for  the  use  of 
only  the  compiler.  A  textual  diversion  stream  is  one  which  accepts  text — it  is  copied  directly  to  a 
file.  A  documeniaiion  diversion  stream  is  similar,  but  additionally  implies  that  the  text  is  some 
form  of  documenuition,  and  transformations  may  be  made  on  it  in  the  diversion  process.  ITiere 
arc  also  types  of  form  diversion  streams  which  cause  the  diverted  forms  to  appear  "at  top  level", 
as  if  they  had  not  been  diverted  (since  all  form  diversions  can  only  occur  by  means  of  toplcvel 
special  forms),  and  those  which  cause  the  diverted  forms  to  be  immediately  evaluated. 

The  definition  or  redefinition  of  diversion  streams,  if  it  becomes  necessary,  may  be  done  by 
using  the  diversion -stream  clause  in  the  system  definition.  This  clause  has  the  format 
(diversion-stream  name  clause-l  clause-2  ...) 

as  in 

(diversion-stream  interpreter 
( type  toplevel ) 

(predicate  (Isb: not- comp i ling?))) 

( di vers ion-s tream  toplevel 
( type  toplevel ) 

(predicate  t)) 

which  are  tlie  default  definitions  used  for  by  I.SB  for  the  interpreter  and  toplevel  diversion 
streams.  In  genenil,  every  diversion  stream  has  a  type,  which  determines  how  it  handles  data 
sent  to  it  (and  the  restrictions  on  that  data,  i.c.  forms  versus  text),  and  a  predicate  which  is 
evaluated  every  time  an  attempt  is  made  to  divert  something  to  that  diversion  stream,  to  sec  if 
the  diversion  sliuuld  be  performed.  ITic  type  toplevel  handles  only  foims,  and  says  that  they 
should  be  treated  as  if  they  were  "seen  at  Utplcvcl"  in  the  module. 

'Die  types  of  diversion  streams  are: 

toplevel 

This  handles  forms  only,  and  makes  tltcm  "appear  at  toplevel". 

form  A  diversion  stream  of  tliis  type  saves  the  forms  in  a  file.  This  is  done  by  compiling 
them. 

declaration 

Currently  the  same  as  form.  This  is  for  saving  information  needed  for  compilation  of 
things  (like  declarations  and  macros). 

text  Handles  text.  The  text  is  copied  to  a  file. 

documentation 

I  ike  text,  but  additionally  implies  that  the  text  is  dociimcnt.ilion;  ir.msformations  may 
be  m.tdc  on  ii  when  it  is  diverted.  See  section  S.2.1.  page  5.1. 
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eval  Forms  diverted  to  such  a  diversion  stream  arc  immediately  evaled. 
non-existent 

Attempting  to  divert  anything  to  a  diversion  stream  of  type  non-existent  is  an  error. 
Attempting  to  "load"  one,  if  for  example  the  pubdcl  diversion  stream  of  some 
module  is  of  this  type,  does  nothing.  This  is  used  by  some  LSB  systems  which  are 
not  actually  implemented  with  LSB. 

The  other  clauses  of  a  diversion  stream  definition  are  only  pertinent  to  diversion  streams 
which  produce  files;  these  are  the  same  clauses  which  may  be  specified  for  a  module:  host, 
device,  directory,  and  pathname.  When  LSB  constmets  the  pathname  for  a  diversion  file, 
missing  components  default  to  the  corresponding  components  of  the  pathname  of  tlic  module  (as 
l.SB  calculates  it  to  be  from  the  system  definition),  except  for  the  file-type  and  the  version.  The 
version  defiiults  to  the  version  of  the  module  being  read  or  compiled.  The  file-type  defaults  to 
the  name  of  the  diversion  stream,  with  some  exceptions  dependent  on  the  host  file  system; 


rsion  Stream 

Li  spM 

NIL 

Three-character 

pubdcl 

pubdq! 

pubdvl 

pdc 

sysdcl 

sysdql 

sysdvl 

sdc 

moddc 1 

moddql 

sysdvl 

mdc 

pubdoc 

pubdoq 

pubdov 

pdo 

sysdoc 

sysdoq 

sysdov 

sdo 

moddoc 

moddoq 

moddov 

mdo 

macros 

maqros 

mavros 

mac 

These  exceptions  exist  cither  (as  in  the  ease  of  TOPS-10)  to  compactify  the  name  into  3 
characters,  or  (more  commonly)  because  corresponding  diversion  files  for  different  Lisp 
implementations  will  be  kept  on  the  same  file  system.  If  for  some  reason  these  name  defaults 
need  to  be  hacked,  sec  Isb. 'diversion -fn2s.  page  67. 

There  arc  additional  system  definition  (and  module  specification)  keywords  which  define 
diversion  streams,  and  additionally  default  die  type  and  predicate  of  it: 

textual  -  diversion  -  stream 
text -diversion -stream 
text-divstream 

Ibis  defaults  the  diversion  stream  to  be  of  type  text.  Ihc  predicate  defaults  to 
(lsb:compiling-to-file?);  the  text  will  only  be  diverted  if  a  module  is  being  fully 
compiled. 

documentation  diversion -stream 
doc  -divstream 

Ibis  defaults  tbe  diversion  stream  to  be  of  type  documentation.  The  predicate  defaults 
to  (Isb  divert  documentation?). 

form -diversion  -stream 
form  divstream 

I  he  diversion  stream  will  be  by  default  of  type  form.  Forms  (lisp  code)  diverted  to  it 
will  be  compiled  into  a  file.  Ihe  predicate  defaults  to  (Isb.compiling-to-file?). 

declaration  diversion -stream 
del  divr.troam 

Ihe  divcrstion  stream  will  be  by  dcr.iull  id  type  declaration.  Forms  diverted  to  it  will 
be  compiled  into  a  file;  the  predicate  used  by  default  is  (lsb;divert  declarations?). 
Ibis  ivpe  of  diversion  strc.im  is  distinct  from  form  because  it  maj  do  additional 
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processing  or  setup  on  the  forms,  such  as  implicitly  diverting  some  kinds  of  setup  forms 
first;  this  is  not  done  yet  however. 

Here  are  some  predefined  predicates  for  use  with  diversion  stream  definitions. 

1sb:comp111ng? 

lliis  returns  t  if  evaluated  during  a  compilation,  nil  otherwise.  It  will  return  nil  if  called 
during  die  loading  of  a  file  (by  Isb-load  only,  sorry),  even  if  during  a  compilation. 

Isb :  not-comp1  Ung? 

Kquivalent  to  (not  (lsb;compiling?)). 

Isb  :compn  Ing-to-f  lie? 

I  his  returns  t  if  evaluated  during  the  compilation  of  a  file  to  a  file,  nil  otherwise  (and 
during  loading  of  a  file).  This  is  the  default  for  randomly  defined  diversion  streams. 

1sb:d1 vert-documentat1on7 

Ihis  returns  t  if  lsb:compiling-to-file?  would,  and  if  the  inhibit -documentation - 
production  Hag  was  not  set  by  specification  of  that  clause  in  the  system  definition  or 
module  siiecilicacion.  Ihis  is  the  default  diversion  stream  predicate  for  all  diversion 
streams  defined  with  the  textual -diversion -stream  clause.  Note  diat  if  one  uses  the 
diversion -stream  clause  but  specifies  a  type  of  text  or  documentation  (as  explained 
below),  the  default  predicate  is  still  (lsb;compi(ing-to-file?). 

Isb :d1 vert-declarations? 

Ibis  is  tlic  default  predicate  used  for  declaration  diversion  streams.  It  is  currently 
equivalent  to  lsb:compiling-to-file?  (q.v.).  but  may  become  more  complex  as  facilities 
become  better  adapted  to  the  use  of  a  Lisp  environment  with  a  resident  compiler,  such  as 
l.isp  Machine  l  isp. 


8.1  Form  Diversion  Streams 

When  an  1  Sll  definition  is  processed,  the  information  from  it  is  partitioned  up  on  the  basis 
of  what  needs  to  be  known  where,  and  the  fonns  generated  are  "sent"  to  various  fonn  diversion 
strc.inis.  An  ex.unple  of  this  is  given  in  section  2.5,  page  7: 

(  def  i  ne  pul)  1  i  c  routi  ne  (squareS  (flonum  n)) 

(dels  (value-type  flonum)) 

(  •$  n  n  ) ) 

This  siiys  that  squareS  is  a  routine  of  one  argument  (n.  a  flonum)  which  always  returns  a  flonum 
result.  What  is  actually  produced  from  this  definition  is  something  more  on  the  order  of 
( di ver t- f orms - to  (pubdcl  compilation-environment) 
dcchiriiiMin  /nrsqiiareS ) 

(divert  fonns-to  (toplevel) 

((lefun  S()uare$  (n) 

hh  ill-declarations  if  needed 
(•$  n  n))) 

That  is,  ihe  definition  ol  squareS  is  sent  to  the  toplevel  dive^ion  stream,  which  is  like  h.oing  it 
specified  .It  lopkwcl  in  Ihe  source  file.  Ihe  declaialions  for  squareS.  however,  aie  sent  to  die 
pubdcl  and  compilation  environmemt  divcision  stre.ims;  the  former  is  a  dcchiiaiian  diversian 
siiCiiia  for  public  dcclar.itinns.  .iiid  Ihe  laiier  is  n,il  diversion  stream  which  has  ,i  predic.ile  such 

Ml  :l  smWK’.DlVDl  I  (i.l  2')-.lliN  }<l 


Textual  Diversion  Streams 


52 


l.SB  Manual 


that  the  forms  will  be  evaluated  immediately,  but  only  during  compilation. 

dlvert-forms  to  Special  Form 

(divert-forms-to  diversion-stream- names 
form-1  form- 2  .  .  .  ) 

I'his  is  the  primitive  macro  for  initiating  fonn  diversions.  It  is  only  valid  as  a  "toplevel 
form"  in  a  module  (similar  to  defun  and  eval-when).  One  may  not  nest  this  construct, 
and  the  behaviour  of  eval-when  and  declare  inside  of  it  is  not  defined.  What  is  usually 
more  convenient  to  use  than  tliis  is  forms-needed-for: 

t 

forms-needed-for  Special  Form 

(  forms-needed-for  needed- for^ keyword-list 
fonn- 1  form- 2  .  .  .  ) 

This  is  similar  to  divert-forms-to.  but  accepts  needed-for  keywords,  as  described  in 
section  2.6.  page  8.  If  a  keyword  implicitly  needs  a  visibility  class,  private  is  assumed; 
hence,  in  this  context,  the  compilation  keyword  is  equivalent  to  private -compilation. 


8.2  Textual  Diversion  Streams 

m 

textual  diversion  streams  are  diversion  streams  whose  primary  operation  is  manipulation  of 
text,  rather  than  foims.  'Ihcre  are  two  types  of  diversion  streams  defined  which  handle  text: 
text,  which  transcribes  the  diverted  text  literally,  and  documentation,  which  may  perform  some 
transfonnations  in  the  process. 


Text  diversion  is  effected  by  an  extension  of  tlie  read-time  conditional  inclusion  mechanism: 
tlie  exclusion  of  text  by  the  {  reader  macro  allows  its  inclusion  test  to  specify  what  diversion 
streams  die  excluded  text  should  be  diverted  to.  There  is  additionally  provision  for  actions  to  be 
taken  before,  after,  and  during  the  exclusion  process. 


divert-to  Inclusion  Tester 

(divert -to  divstrcam-l  divsircam-2  ...)  is  the  simplest  inclusion  test  for  diverting  text.  It  is 
only  for  use  in  read-time  conditional  inclusions,  as  there  is  no  other  conditional  inclusion 
mechanism  which  can  provide  a  source  of  "text".  111115. 

{(divert-to  pubdoc) 

This  is  some  documentation. 

} 

diverts  all  of  the  text  from  the  first  to  the  last  to  the  pubdoc  diversion  stream. 

/*• 

< 

There  are  several  other  inclusion  tests  for  use  with  diverting  dixuinentation  in^-'jnore 
compile, lied  w.iys,  r.iiher  lli.in  just  .i  liter, il  ti.msc ription  .is  divert-to  does.  It  is  therefore  possible 
for  tranfoim.iiions  on  ihe  diverted  text  to  iK’Cur  both  .is  a  result  of  the  wav  the  diversion  stream 
handles  the  diversion  oper.ition.  and  as  a  result  of  the  way  the  text  is  sent  to  tlie  diversion 
sire.im.  Ihese  coinplications  are  described  in  chapter  9.  p.ige  55.  Many  of  them  only  function  on 
documeotntion  diversion  streams.  ,is  they  implicitly  perform  higher-level  formatting  operations 
which  only  documeni.ition  liiversion  stre.ims  can  supply. 
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8.2.1  Documentation  Diversion  Streams 

Documentation  diversion  streams  differ  from  plain  text  diversion  streams  mainly  by  extension. 
A  documentation  diversion  stream  has  a  documentation -type,  which  may  be  specified  with  the 
documentation -type  clause  in  the  diversion  stream  definition,  and  it  may  be  defaulted  for  all 
d(Kumcntation  diversion  streams  by  being  used  as  a  system  definition  or  module  specification 
clause.  I  here  arc  two  diKumcntation  types  currently  defined;  bolio,  the  default,  and  tex.  ITiis 
nonnally  only  manifest  themselves  when  the  more  complicated  documentation  diversion  inclusion 
tests  arc  used;  these  arc  documented  fully  in  chapter  9. 

(define- system  hairi ly-documented 

(built-on  this  that  the-other-thing) 

( documentati on-type  tax) 

( documentati on -divers ion- stream  extra- doc 
(documentation-type  R)) 

(modules  foo 

(bar  (documentation-type  bolio)) 

(baz  (documentation-diversion-stream  pubdoc 
(documentation-type  bolio))))) 

The  hairily-documented  system  has  a  default  documentation-type  of  tex;  this  is  implied  by  the 
(documentation -type  tex)  at  top  level  in  the  system  definition.  All  documentation  diversion 
streams  which  arc  not  otherwise  specified  will  default  this  way.  For  the  bar  module,  however, 
the  default  d(Kunicntation  type  is  bolio.  Note  that  the  type  of  defaulting  going  on  here  does  not 
affect  the  extra-doc  diversion  stream,  since  the  documentation  type  for  that  never  gets  defaulted; 
for  all  modules,  it  will  be  of  documentation  type  R.  l-ikcwise,  for  the  baz  module,  all  the 
documentation  diversion  streams  will  have  dcKumcntation  type  tex  except  for  extra -doc  and 
pubdoc,  which  wilt  be  R  and  bolio.  Note  tliat  there  is  no  R  documentation  type  presently. 

8.3  Pre-Defined  Diversion  Streams 

Here  are  the  diversion  speams  initially  defined  in  an  LSB  environment, 
pubdoc 

A  documentation  diversion  stream,  intended  for  public  documentation.  Its  predicate 
causes  diversion  to  occur  only  when  the  containing  module  is  being  compiled  and 
documentation  diversion  is  enabled;  it  uses  the  lsb:divert -documentation?  predicate. 

sysdoc 

Similar  to  pubdoc,  but  for  system  documentation, 
moddoc 

A  documentation  diversion  stream,  intended  for  private  documentation.  By  default  this 
diversion  stream  has  a  predicate  of  nil,  so  text  sent  to  it  goes  nowhere;  that  predicate 
may  h»)wcvcr  be  modified  in  the  system  definition. 

info  I  ike  pubdoc.  I  his  is  provided  somewhat  spuriously.  It  ct)uld  be  used  for  suc  i  things 
as  online  documcnuilion. 

pubdcl 

This  is  a  declaration  diversion  sire.im,  for  public  declarations.  Its  predicate  causes 
diversion  to  (klui  only  when  the  module  is  being  compiled. 

Sysdcl 

I  ike  pubdcl.  liu  system  declarations. 
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moddcl 

For  private  declarations.  This  normally  has  predicate  of  nil.  causing  no  diversions.  That 
may  be  changed  by  the  user  if  it  is  found  to  be  needed  for  some  obscure  forward- 
reference  problem. 

compilation  -  environment 

An  eval  diversion  stream,  with  a  predicate  that  causes  the  diversion  (and  hence 
evaluation)  to  occur  only  in  the  compiler. 

readti  me  -  environment 

In  a  compilation  environment,  this  is  defined  as  an  eval  diversion  stream,  causing  the 
forms  diverted  to  be  immediately  evaluated:  otherwise,  it  is  a  toplevel  diversion  stream, 
tlius  being  equivalent  to  interpreter.  The  result  of  this  is  that  the  "diversion"  occurs  in 
the  processing  environment,  so  may  be  used  to  modify  the  LSB  environment,  or  the 
reading  environment.  This  may  be  renamed  to  processing -environment. 

interpreter 

This  is  a  diversion  stream  of  type  toplevel,  defined  with  a  predicate  which  causes  no 
diversion  when  being  processed  by  the  compiler:  thus, 

( di vent-forms-to  (Interpreter)  ...) 

acts  like 

(eval-when  (eval )  . . . ) 
compiler -toplevel 

A  toplevel  diversion  stream  with  a  predicate  complementary  to  that  of  the  interpreter 
diversion  stream. 

toplevel 

A  toplevel  diversion  stream  with  a  predicate  of  t.  This  is  useftil  if  the  forms  to  be 
diverted  not  only  should  be  processed  "at  top  level"  in  the  module,  but  also  sent 
somewhere  else  (e.g.,  to  the  pubdcl  diversion  stream). 

macros 

lliis  diversion  stream  is  used  primarily  for  macro  definitions  which  arc  not  needed  in  a 
totally  compiled  system  (see  section  5.5.1,  page  34).  In  Maclisp,  it  is  by  default  a  form 
diversion  stream  which  will  compile  its  forms  into  a  file,  when  used  in  the  compiler, 
and  do  nothing  in  the  interpreter  (like  pubdcl).  In  Lisp  Machine  l.isp  and  NIL,  it  will 
by  default  be  a  toplevel  diversion  stream,  so  that  the  forms  in  it  are  put  in  the 
compiled  output  file. 
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9.  Documentation  Diversion 

Section  8.2  described  textual  diversion  streams,  and  how  text  may  be  sent  to  them.  This 
chapter  discusses  more  advanced  facilities  for  diverting  text  and  producing  documentation. 

public-documentation  Inclusion  Tester 
system-documentation  Inclusion  Tester 
private-documentation  Inclusion  Tester 
online-documentation  Inclusion  Tester 

Ihcse  routines  arc  for  use  as  inclusion  tests.  They  are  equivalent  to  (divert- 
documentation-to  divstream)  for  the  appropriate  diversion  stream:  pubdoc,  sysdoc, 
moddoc.  or  info. 

divert-documentatlon-to  Inclusion  Tester 

(divert -documentation -to  divstream-l  divstream-2  ...)  is  an  inclusion  test  which  always 
fails,  and  causes  the  text  within  curly-brackets  to  be  interpreted  as  documentation  and  sent 
to  the  specified  diversion  streams.  Example; 

{(divert-documentatlon-to  pubdoc ) 

.chapter  "Hacking  Around" 

This  is  a  test  of  the  emergency  broadcast  system. 

It  is  only  a  test.  Had  it  been  a  real  emergency  you 
would  have  run  out  of  list  storage. 

} 

This  inclusion  test  is  not  equivalent  to  divert-to  (page  52).  The  enclosed  text  is  output 
within  a  "documentation  block",  which  means  that  it  will  be  preceded  by  a  blank  line; 
this  is  irrespective  of  whether  a  newline  immediately  follows  the  inclusion  test,  as  such  a 
newline  is  ignored. 

When  I. SB  defines  operations  or  variables,  it  records  various  attributes  of  them  in  the 
environment  (either  compiler  or  interpreter).  J'his  information  is  then  used  by  the  following 
routines  to  supplement  user-supplied  diKumentalion.  For  operations  (routines,  macros,  and 
special- forms,  but  not  compile-timc-macros),  tliis  information  includes  such  things  as  the  type  of 
definition,  information  about  the  prototype  call,  and  the  value-type.  For  both,  most  importantly, 
it  includes  the  diversion  stream(s)  to  which  documentation  about  the  object  defined  is  to  be  sent 
to.  The  following  inclusion  tests  utilize  this  information  in  order  to  figure  out  where  to  send  the 
excluded  text. 

document-routine  Inclusion  Tester 
document-routines  Inclusion  Tester 

Ihcse  two  inclusion  tests  are  identical;  both  names  arc  provided  for  euphony, 
(document -routine)  as  an  inclusion  test  will  diKumcnl  ihc  most  recently  defined  routine; 
(document- routine  a)  will  document  a.  and  (document -routines  a  b  c)  will  diKunicnt 
a,  b,  and  c  as  a  group,  for  an  clfcct  similar  to  that  in  this  text  here.  For  example,  one 
might  do 
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( def i ne-publ i c-open-codable-routi ne  (square  (number  n)) 

(dels  (value-type  number)) 

(times  n  n)) 

{(document- routine) 

e3squaree*  returns  the  square  of  Its  argument. 

} 

( def 1 ne-publ 1 c-open-codable- routi ne  (squares  (flonum  n)) 

(dels  (value-type  flonum)) 

(•$  n  n) ) 

( def 1 ne-publ i c-open-codable-routi ne  (squares  (fixnum  n)) 

(dels  (value-type  fixnum)) 

(•  n  n)) 

{(document-routines  squares  squareS) 
r3square$e*  and  e3square&r*  are  the  flonum-only 
and  fixnum-only  versions  of  eSsquaree*. 

} 

What  happens  is  the  diverted  text  is  output  between  stuff  computed  from  the  definition 
information,  to  produce  a  special  text-justificr  construct  for  the  particular  type  of 
definition.  What  is  actually  produced  depends  on  the  documentation -type  of  the 
diversion  stream(s);  this  is  described  later  in  this  chapter. 

document-variable  Inclusion  Tester 
document-variables  Inclusion  Tester 

nicse  is  similar  in  form  and  function  to  document -routine. 

( def 1 ne-sy stem- vari able  •f robozz* 

(default-init  ( create-a-crock ) ) ) 

{ ( document -var  table) 

This  is  a  disgusting  crock. 

} 

When  one  is  utilizing  the  same  source  text  in  different  Lisp  implementations,  it  is  often 
unnecessary  to  redundantly  produce  d<Kumcntation  from  both.  The  default  predicate  used  by 
d(x:umcntation  diversion  streams  (lsb:divert-documentation?,  page  51)  checks  the  flag  set  by 
inhibit-documentation- production  system  definition  option,  which  says  that  documentation 
should  not  be  diverted.  For  example,  the  pretty-print-definition  system  is  defined: 
(define-system  pretty-print-dafinltion 
(directory  format) 

(built-on  loop  sharpsign  backquote  {PDP-10  user-hunk}) 

( users  -  imp  1 i c i t ly -need  write) 

{{except  for  POP  10)  (  inhibit-documentation-production)} 
(modules  ppdef  ppdesc) 

) 

When  address  space  is  a  consideration  and  the  above  I'pcration  and  variable  documciiUrtion 
(.icditics  arc  not  being  used,  one  should  also  use  the  inhibit  documentation -production  option, 
bee. lose  m  addition  to  inhibiting  the  diversion  of  documenUUion,  it  tells  l.SIl  not  to  record 
inroiin.ilion  .iboiit  the  definitions. 
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9.1  The  Bolio  Documentation  Type 

Bolio  is  a  text  justificr  written  in  PDP-10  Maclisp.  It  comes  with  predefined  operators  and 
conventions  for  documenting  Lisp  programs;  because  of  this,  it  is  the  default  documentation  type. 
Bolio  was  used  to  produce  the  Lisp  Machine  Manual,  and  this  document 

The  output  produced  for  Bolio  by 

( def i ne-publ i c-open-codabl e-routi ne  (square  (number  n)) 

(dels  (value-type  number)) 

(times  n  n)) 

{( document- rout i ne ) 

F3squaree*  returns  the  square  of  its  argument. 

} 

looks  like 

.defun  square  e 1( numbere*Vne 1 ) e* 

c3squareE*  returns  the  square  of  its  argument. 

. end_def un 

All  of  tliat  randomness  after  square  on  the  .defun  line  is  font  switching  and  spacing  so  that 
Bolio  docs  not  need  to  do  any  parsing  of  the  argument  descriptions.  I'he  output  produced  by 
( def i ne-pub 1 i c-open-codable-rout i ne  (squares  (flonum  n)) 

(dels  (value-type  flonum)) 

( *$  n  n  ) ) 

( def i ne-publ i c-open-codable-routi ne  (squareSi  (fixnum  n)) 

(dels  (value-type  fixnum)) 

(*  n  n)) 

{(document-routines  square!  square&) 
f3square$f*  and  e3square&r*  are  the  flonum-only 
and  fixnum-only  versions  of  eSsquaree*. 

} 

looks  like 

.defun  square!  r 1 ( f lonumc*Vnt 1 ) e* 

.defunl  square&  f 1 ( f i xnume ‘Vne 1 ) e • 
r3squareSf*  and  f3square&f*  are  the  flonum-only 
and  fixnum-only  versions  of  E3squarec*. 

. end_def un 

Different  types  of  definitions  produce  different  documentation  operators,  in  a  similar  format, 
differing  only  in  the  text-justifier  commands  used  and  the  argument  descriptions:  only  routine 
definitions,  producing  .defun,  output  any  argument  descriptions.  Variable  definitions  use  .defvar. 
•defvarl.  and  .end_defvar,  macro  definitions  use  .defmac,  .defmaci,  and  .end_defmac,  and 
special  forms  (or  routines  t)r  macros  which  have  tlic  document -as -special -form  option  specified 
in  their  declarations)  use  defspec,  .defspecl.  and  .end_defspec. 

l-xccpt  on  Multics  (which  docs  not  do  case-conversion  on  input),  variable,  argument,  data 
type,  and  operation  names  are  converted  to  lower  case  when  output.  Call  mapping  keywords, 
such  as  optional,  are  lapiiali/cd.  In  Lisp  implementations  with  packages,  some  heuristics  arc 
used  to  attempt  to  determine  htiw  the  defined  object's  name  should  be  printed.  Lor  routines,  the 
names  of  the  .ugtmients  will  always  be  output  without  any  package  information. 
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9.2  The  TEX  Documentation  Type 

The  output  produced  by  the  tex  documentation  type  for  the  square  example  of  the  previous 
section  looks  like 

\defun  SQUARE  \argtype{number}{n} . 
user- text 

Note  that  no  indication  of  the  end  of  the  text  is  given,  although  there  will  be  a  blank  line  there. 
The  tex  fonnat  in  general  produces  calls  like  argtype  above  rather  than  pre- formatting  the  type 
and  call-mapping  keyword  information;  e.g.,  the  routine 

( def i ne-publ i c-routi ne  (foo  (quoted  a)  (optional  (flonum  b))) 

...) 

would  produce  the  \defun  header 

\defun  FOO  \quot0d{quot0d}{a} 

\optional { options l}{\argtype{ flonum} {b}} . 
except  that  it  would  all  be  on  one  line.  The  reason  quoted  and  optional  appear  to  be  duplicated 
above  is  that  the  name  in  braces  is  the  actual  keyword  used  in  the  definition,  which  may  be 
different  from  the  macro  name.  Currently,  the  routine,  macro,  or  variable  name  is  not  lower- 
casified,  although  the  variable  names  and  keywords  are.  Like  bolio,  the  tex  documentation  type 
can  produce  multiple  \defuns  in  a  block,  by  using  \defun1.  It  will  also  produce  calls  to 
\defvar.  \defmac,  and  \defspec,  and  \defvar1  etc.  Unlike  bolio,  all  of  the  operation 
dtKumenting  macro  calls  produced  will  contain  the  argument  information  from  the  prototype  call. 

The  full  list  of  argument  descriptor  macros  used  Is; 

\optional{kn'(fl{  innards} 

\  rest  {kwil)[in  nards) 

where  kwd  is  tlic  actual  call-mapping  keyword  used,  and  innards  is  the  remainder  of 
the  argument  description. 

\quoted  {  k  ml)  { innards) 

Similar  to  the  above. 

\argtype{  kwd)  { variable) 

The  \argtype  will  be  the  most  deeply  nested  macro  call  if  it  is  present,  so  its  second 
"argument"  can  only  be  the  variable  name. 

ITius  the  output  produced  for  the  variable  args  in  the  prototype  call  (foo  (any-number-of 
(quoted  (fixnum  args)))  looks  like 

\rest{any -  number -of } { \quoted{quoled} { \arg ty pe{f i xnum}{args)}} 

Iherc  is  no  existing  p.ickage  of  IT'-X  macros  to  do  anything  with  this  output,  yet. 
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10.  Getting  LSB 

10.1  The  LSB  Compiler 

LSB  provides  its  own  standard  compiler  interface.  It  is  very  similar  to  whatever  standard 
compiler  interface  is  normally  provided,  but  offers  one  option  (as  a  default)  which  none  do;  it 
reads  and  macro-processes  tlie  input  file  fully  before  it  begins  compilation.  That  is,  it 
incrementally  reads  in  the  file,  expanding  toplevel  macros.  LSB  definitions  and  diversions, 
declares,  eval-whens,  and  includes,  but  instead  of  immediately  outputting  or  compiling  the 
resultant  forms  as  an  ordinary  compiler  would,  they  are  buffered  up.  Only  when  all  of  the  input 
has  been  processed  are  tlic  forms  compiled. 

This  is  a  very  useflil  action,  due  to  the  way  LSB  works.  Because  all  of  the  declarative 
information  about  defined  objects  in  LSB  is  derived  from  the  definition  form,  one  does  not 
declare  everything  that  needs  declaring  at  the  front  of  the  file;  thus,  this  first  pass  allows  LSB  to 
extract  all  of  the  declarations  (and  macro  definitions)  which  will  be  needed  for  the  compilation 
before  the  compilation  starts.  Note  that  the  reading  of  the  file  is  done  incrementally  with  this 
fonn  processing:  one  may,  in  something  like  an  eval-when  or  in  a  toplevel  macro  call  (which 
the  module  form  at  the  front  of  the  file  is)  modify  reader  attributes,  such  as  syntax  and  input 
radix.  ITiis  also  obviates  the  need  for  declare-routine  (page  40)  and  declare -variable  (page  46) 
in  many  cases. 

Having  the  file  processed  in  this  manner  does  not  solve  all  forward-reference  problems;  only 
those  "one  level  deep",  if  that  much.  LSB  makes  use  of  some  declaration  information  when  it 
expands  out  definitions,  and  information  it  needs  should  be  around  before  one  of  its  forms  is  to 
be  prwessed.  ITius,  if  one  docs  something  like 

(def ine-publ ic-routine  (ilk  (triple  x)) 

(dels  ( type-check-argument  x)) 

...) 

( def i ne -pub  1 i c-data- type  triple 
(predicate  triplep) 

( cont i nue-wi th  brand-x-ob ject ) ) 

the  ilk  routine  will  not  have  type  checking  performed  for  it.  because  at  the  time  LSB  creates 
type-checking  code  the  triple  data-type  (and  the  asswiated  mechanism  for  doing  argument  type 
checking  for  that  type)  has  not  been  defined.  The  same  could  be  umc  for  top-level  calls  to 
macros  which  arc  defined  later  in  the  file: 

( def i ne-a-f rob  foobar) 

( def i ne-publ ic-macro  ( def i ne-a-f rob  name) 

...) 

Whether  or  not  tlic  ordering  matters  in  this  last  case  depends  on  what  (define- a-frob  foobar) 
cxp.iiids  into;  for  safety,  constructions  like  this  should  be  ordered  properly.  Note  also  tliat  this 
ordering  constraint  is  in  fact  that  which  would  be  necessary  to  load  the  code  interpreted  anyway, 
since  tlicrc  is  no  pro-pass  made  when  a  source  file  is  loaded  into  a  lisp. 
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10.1.1  The  Maclisp  Compiler 

The  PDP-10  l.SB  compiler  is  a  normal  PDP-10  compiler  with  LSB  in  it.  running  the  LSB 
compiler  interface.  The  command  interface  to  it  is  the  same  as  the  ordinary  PDP-10  Lisp 
compiler,  although  it  will  run  the  LSB  file-processing  interface  as  described  above.  If  for  some 
reason  this  LSB  interface  is  undesirable,  say  the  file  is  particularly  large  and  docs  not  fit  into  the 
compiler,  then  one  can  disable  this  mode  by  negating  the  "L"  compiler  switch:  for  example,  to 
the  compiler’s  command-processing  loop,  saying: 
myfile  (t-1) 

On  the  ITS  operating  system,  the  LSB  compiler  may  be  invoked  with  the  tLSBCL  command. 
■ITicrc  is  currently  no  LSB  compiler  available  on  non-l  l'S  operating  systems. 

In  Multics  Maclisp,  there  is  also  currently  no  saved  LSB  compiler  available.  I'hc  special  LSB 
file-processing  interface  is  not  available  either.  One  may.  however,  bootstrap  up  an  LSB  in  an 
ordinary  compiler  by  placing  the  following  form  at  the  front  of  the  source  file,  before  the  module 
form: 

(eval-when  (compile) 

(or  (status  feature  LSB) 

(load  ">udd>Mathl ab>LSB>compi lation-environment.lisp"))) 

This  form  will  thus  work  both  in  a  compiler  without  LSB,  and  in  a  saved  LSB  compiler  if  and 
when  one  becomes  available.  One  must  use  a  compilcr/lisp  which  understands  die  eval-when 
special  form;  LSB  depends  on  it.  If  the  source  file  is  also  to  be  used  in  Lisp  implementations 
other  than  Multics,  the  Multics  feature  should  be  checked  for  too: 

(eval-when  (compile) 

(and  (status  feature  Multics) 

(not  (status  feature  LSB)) 

(load  ">udd>Math 1 ab>LS0>compi lation-envl ronment .lisp"))) 


1 0.1. 2  Oil  the  Lisp  Machine 

At  some  future  time,  LSB  should  exist  saved  on  a  disk  band.  Currently,  one  may  cause  LSB 
to  be  loaded  by  doing 

(load  "MC;LSB;LISPM  LOAD") 
which  loads  every  thing,  and  is  thus  a  bit  time  consuming. 

lo  compile  an  LSB  module,  do  rwi  use  qc-file: 

Isbcom  oi/ilf  Aoplion.il  outfile  /xiekogc-spec 

Ihis  IS  simil.ir  to  qc-file.  but  runs  the  LSB  compiler  interface.  Ihc  arguments  Isbcom 
tako  arc  interpreted  tlie  s.ime  way  qc  file  interprets  llicm  (q.v.). 


Ml  I  SHIXK  ;(  OMI'l  |{  25 


29-JUN-8I 


I. SB  Manual 


64 


Interpreted  LSB 


10.1.3  On  the  VAX 

To  be  written  when  developed.  It  is  suspected  that  it  may  not  be  possible  to  compile  LSB  on 
the  10  for  the  VAX  because  of  address-space  limitations.  LSB  use  on  the  VAX  will  probably  not 
differ  drastically  from  that  on  the  PDF- 10. 


10.2  Interpreted  LSB 

On  ri'S,  LSB  is  available  as  a  dumped  environment  under  the  name  LSB.  This  environment 
contains  some  things  which  arc  not  strictly  a  part  of  LSB  but  which  are  commonly  used  by  most 
current  LSB  users.  If  demand  indicates,  this  can  be  cleaned  up. 

Dumped  subsystems  on  ITS  very  often  will  need  LSB  in  them  if  any  code  is  going  to  be  run 
interpreted  in  tlicm,  but  for  production  purposes  this  may  be  undesirable.  It  is  possible  to  create 
versions  of  Jirmped  subsystems  which  do  and  do  not  contain  LSB.  and  which  share  the  portion 
of  tlie  subsystem  not  containing  LSB.  'Fhis  is,  in  fact,  a  general  feature  of  Maclisp  on  I  TS.  and 
has  nothing  to  do  with  LSB;  it  is  documented  elsewhere.  Ihe  file  LSB  LILES  on  the  I.SB 
directory  will,  when  loaded,  load  in  those  parts  of  LSB  normally  needed  for  running  interpreted 
code,  and  set  up  autoload  properties  for  some  others  which  are  only  rarely  used.  All  LSB 
autoload  properties  in  LDP- 10  Maclisp  arc  of  the  form  ((Isb)  ...),  so  on  a  non-ITS  system  the 
atom  Isb  may  be  given  a  ppn  property  if  needed.  Much  LSB  code  automatically  defaults  the  Isb 
ppn  property  to  that  for  lisp. 

On  Multics,  the  file  >udd>Mathlab>LSB>lsb-loader.lisp  is  equivalent  to  the  LSB  FILLS  file 
of  PDP-IO  Maclisp--it  loads  only  those  parts  of  LSB  normally  needed  for  interpretation. 

ITic  Lisp  Machine  programming  environment  is  such  that  getting  LSB  for  interpretation  is  the 
same  as  getting  it  for  compilation. 
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11.  Coming  Attractions 

These  are  random  notes  on  things  which  arc  either  under  development  or  are  being 
considered. 

In  PDF- 10  Maclisp,  it  is  possible  for  tlic  file  properly  list  to  be  parecd  and  used  in  a 
l.HDIT/HMACS  combination,  to  allow  the  proper  binding  environment  to  be  csuiblishcd  when 
code  is  transferred  from  the  HMACS  to  tlic  LISP.  ITiis  can  use  the  LSB  option  of  the  file 
property  list.  An  experimental  version  of  this  has  been  tried,  but  tlic  minimal  hooks  necessary  do 
not  yet  exist  with  the  system-supplied  I.l-DIT. 

One  problem  with  using  LSB  is  tliat  things  which  arc  logically  built-on  it  arc  then  required 
to  use  LSB  if  they  arc  to  properly  have  their  compilation  (for  example)  environment  established. 
In  most  cases,  however,  loading  the  various  pubdcl  files  of  the  sysicm(s)  involved  will  suffice.  A 
relatively  small  amount  of  code  would  be  needed  to  support  the  loading  of  tJicsc  files  into  a  bare 
compiler.  This  is  mainly  applicable  to  Lisp  environments  like  Maclisp  where  the  compilation 
environment  is  distinct  from  the  runtime  environment.  For  the  Lisp  Machine,  the  potential  exists 
for  either  causing  the  contents  of  the  declaration  diversion  files  to  be  "expanded  out"  .so  that  they 
do  not  utili/c  LSB.  or  again,  to  simply  have  some  special  code  to  allow  them  to  be  loaded.  The 
latter  would  require  tlierc  to  be  an  LSB  package.  Yet  another  alternative  for  tlic  Lisp  Machine 
(or  similar)  implementation  is  to  cause  all  of  the  declaration  infomiation  to  be  output  into  the 
compilation  output  file;  this  differs  from  splitting  it  into  multiple  (c.g..  qfasl.  pubdcl.  sysdcl) 
files  in  that  tlierc  would  be  no  duplication  of  code.  Again,  iliis  might  possibly  be  done  either  by 
haling  .some  bootstrap  LSB  code  around  at  load  time,  or  by  convincing  LSB  to  "open-code"  the 
declaration  info  it  outputs;  this  last  is  only  moderately  space-consuming,  as  much  of  the  stuff 
output  involves  declaration  info  which  is  redundant  with  the  runtime  environment,  and  error 
checking. 

It  is  possible  to  compile  portions  of  an  LSB  module  "out  of  context".  All  that  needs  to  be 
done  is  to  run  the  LSB  pre-processing  step  (section  10.1.  page  59)  over  the  original  file  to  extract 
.ill  private  declarations,  and  then  compile  the  file  as  if  it  were  that  module  itself.  Appropriate 
fudging  of  the  diveision  streams  is  necessary  to  ensure  that  erroneous  diversions  arc  not  created 
for  that  module,  hut  is  not  difficult.  An  experimental  version  of  tliis  has  been  tried,  and  all  tliat 
IS  necessary  is  to  put  a  patch -module  form  at  the  front  of  the  file,  instead  of  using  module. 
I  his  facility  is  not  available  by  default  yet,  but  probably  will  be  soon. 
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12.  Extending  LSB 

This  chapter  describes  various  methods  and  conventions  which  may  be  used  to  extend  or 
customize  I.SB  in  some  way.  Ihc  contents  are  somewhat  haphazardly  organized,  and  in  many 
ca,ses  there  is  missing  description  of  how  to  do  things,  but  it  is  suitable  as  a  reference  for 
relatively  stable  but  internal  facilities  of  I.SB.  Nothing  in  this  chapter  should  be  used  frivolously; 
it  is  primarily  compensation  for  lack  of  better  "public"  facilities.  Also,  any  changes  to  the 
contents  of  this  chapter  would  warrant  a  warning  to  the  INFO-LSB  mailing  list,  so  it  is  safer  to 
use  what  is  listed  here  than  just  anything  you  might  find  in  the  source  code. 

If  you  use  any  facilities  documented  here,  it  is  recommended  that  the  system  using  them  be 
buill-on  the  Isb  system.  Although  use  of  some  things  here  docs  not  require  this,  not  all  macro 
definitions  and  declarations  may  be  pre-loaded  in  all  Lisp  implementations. 
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12.1  LSB  Keyword  Comparison 

Here  are  the  various  routines  for  comparing  symbols  for  LSB  keyword  or  token  equality. 
Note  that  in  all  cases  tlie  "keywords"  being  compared  are  expected  to  be  interned  symbols;  this 
may  matter  in  some  Lisp  implementations. 

Isb: token-equal  token/  token2 

implements  token  equality  testing. 

Isb : token-member  token  list 
1sb : token-assoc  token  a-lisi 
Isb.'token-lookup  token  a-list 

are  analogtius  to  member  and  assoc.  Isbdoken  - lookup  is  like  using  the  Lisp  Machine 
function  memass;  it  returns  the  sublist  whose  car  is  what  would  be  returned  by 
Isb.token -assoc.  That  is, 

(defun  1  sb  :  token-assoc  (token  a-list) 

(car  ( 1 sb ; token- lookup  token  a-list))) 

1sb:kwd- equal  lokent  token2 
1sb:kwd-member  token  list 
1sb:kwd- assoc  token  a-list 
Isb :kwd- lookup  token  a-list 

I  hc  versions  of  the  above  predicates  which  check  using  keyword  equality. 

1sb:kwd-bassoc  token  a-list 

Ihis  is  like  lsb:kwd-assoc  but  bubbles  an  entry  found  forward  in  a-list.  This  should 
only  be  used  for  things  which  may  be  safely  modified. 

Many  LSB  "tables"  arc  implemented  as  association  lists.  Since  the  keys  of  the  entries  cannot 
necessarily  be  compared  with  eg  or  equal,  the  following  macros  may  be  used  to  push  new  entries 
on. 
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Isb;  push -pair  Macro 

( 1 sb : push-pai r  (displace  .  Isbidisplace-macmem) 

Isb: •macro -memo izars ) 

pushes  the  entry  (displace  .  Isb;displace-macmem)  onto  the  list  Isb: ‘macro -memoizers. 
If  the  variable  is  not  bound,  it  will  be  set  to  nil  first.  If  there  is  already  an  entry  for 
displace  there,  it  will  be  removed. 

This  macro  is  defined  such  that  its  expansion  can  be  run  in  a  Lisp  without  TSB  present 
Therefore  it  docs  not  actually  use  keyword  equality,  but  cheats  and  only  uses  token 
equality.  Kor  that  reason,  it  is  imperative  lliat  only  the  "canonical"  form  of  a  keyword  be 
used  in  tliis  manner.  Note  that  if  the  compiler  puts  the  call  to  lsb:push-pair  rather  than 
its  expansion  in  the  compiled  output  file,  tlien  l.SB  will  need  to  be  around  when  the  file 
is  loaded,  fhe  PDF- 10  Maclisp  compiler  normally  will  completely  macro-expand  forms 
before  stuffing  them  into  its  output  file. 

1sb:push-sym  Macro 

I  his  is  just  like  Isb.push-pair,  only  it  does  use  eq  for  comparing  "keys".  It  may  thus  be 
used  for  adding  entries  to  assiKiation  lists  of  (say)  variable  names.  Qualifications  for 
lsb:push-pair  about  runtime  support  apply  here  also. 


12.2  Denning  System  Dennition  Options 

This  section  dcKumcnts  some  facilities  which  may  be  used  for  defining  l.SB  options,  which  arc 
specifiable  in  system  and  module  definitions,  ft  may  be  safely  skipped  by  those  who  arc  not 
interested  in  defining  their  own.  The  facilities  here  should  not  be  used  frivolously;  they  are 
intended  to  be  used  by  the  maintainors  of  systems  which  need  to  provide  special  processing 
environments  for  their  users. 

An  l.SB  option  is  essentially  a  state  which  can  be  encoded  in  some  variablc(s).  It  has  a 
routine  to  dctcnninc  the  value(s)  implied  by  the  option  clause,  and  each  variable  has  a  default 
value  which  is  used  in  the  absence  of  a  specification. 

def  1ne-lsb-opt1on  Macro 

(  doF ine  -  Isb-option  option- keyword  inlerprelalion-fn 
varspec-l  varspcc-2  .  .  .  ) 

defines  opUtnv  keyword  to  be  an  option  for  inclusion  in  a  system  definition  or  module 
specification,  tiiicrpiriaiiunpi  is  a  function  of  one  argument,  the  clause,  which  should 
return  an  asscxi.ition  list  of  the  variables  to  be  modified  and  their  values.  I'ach  of  the 
varspec-i  desvrilics  the  variables  which  may  be  modified  (and  tints  may  need  to  be  bound 
to  set  up  an  I  SM  environment);  it  may  be  either  just  the  variable,  in  which  case  nil  is 
used  as  the  def.iult  value,  or  a  list  of  tiic  variable  and  a  ftirm  to  be  evaluated  to  get  the 
value,  l  ui  example, 

(detun  hack  input-radix  (clause) 

(list  (cons  '(base  (cadr  clause)))) 

( define  1 sb-option  input-radix  hack - i nput- radi x 
( i base  10  .  ) ) 
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def  1ne-1sb-f lag-option  Macro 

lliis  is  really  a  special  case  of  define-lsb-option.  ITie  variable(s)  will  take  on  only  t  or 
nil  as  values.  Kor  example, 

(define-lsb-flag- option  do-argument- type- check i ng 
1 sb : ‘type-check? ) 

defines  do-argument-type-checking  such  dial  either  of  the  clauses 
( do- argument- type-check  i  ng ) 

(do-argument-type-checking  t) 
turns  on  type  eliceking  (by  selling  Isb;* type -check?  to  t),  and 
( do-argument-type-check i ng  nil) 

turns  off  type  checking.  Ihc  syntax  to  define -Isb -flag -option  is  the  same  as  that  to 
define-lsb-option,  minus  the  function. 

Note  that  if  one  desires  an  option  defined  with  define-lsb-option  or  define-lsb-flag-option 
to  take  clTcct  in  tlie  compilation  environment,  one  must  explicitly  use  a  forms -needed -for  form, 
like 

( f orms-needed- f or  (running  public-compilation) 

(defun  hack-input-radix  ...) 

(define-lsb-option  input-radix  ...)) 

unless  the  module  is  needed-for-user-compilation  and  the  option  is  not  used  by  the  system 
which  defines  it. 

By  special  dispensation,  in  Maclisp  it  is  possible  to  load  compiled  calls  to  define-lsb-option 
and  define-lsb-flag -option  into  a  l  isp  which  does  not  have  I.SB  present.  If  I  SB  is  loaded  in 
at  a  later  time,  tliese  options  will  be  in  elfect  (unless  othcrwi.se  redefined). 

12.3  Denning  New  Keadtables 

Isb : *readtables  I'ariable 

This  is  an  asstKiation  list  of  keywords  and  die  readlables  they  represent.  Ivach  "rcadtable" 
itself  is  allowed  (and  in  fact  recommended)  to  be  a  symbol  whose  value  is  die  readublc 
to  be  used,  l  lie  initial  value  of  this  variable  is 

((standard  .  Isbi’standard-readtable)) 

Isb: "standard- readtabla  Variable 

I'hc  value  of  this  is  used  as  the  "standard"  and  default  readtablc  by  I.SB.  It  is  inidalized 
to  die  readtahle  current  when  I.SB  is  loaded  in;  it  will  typically  be  the  one  and  only 
readtablc  in  the  l  isp  environment. 

Ihus.  one  might  define  a  new  readtahle  to  I.SB  by  doing 

( 1 sb : push- pai r  (readtahle  .  Brand-X-Readtabl e ) 

Isb ; *readtab 1 es  ) 

in  some  appropriate  place. 
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12.4  Playing  with  the  System  DePinition 

IsbiestabUsh-sysdaf  system-spec 

system-spec  is  exactly  what  might  be  specified  inside  of  (say)  a  built-on  clause,  as 
described  on  page  12;  either  the  name  of  a  system,  or  a  list  of  the  name  of  a  system, 
and  a  pathname  suggesting  where  to  find  the  system  definition.  ITiis  performs  all  the 
actions  associated  with  searching  for  a  system  definition  (if  it  is  not  already  known!) 
described  early  in  this  manual.  It  returns  a  list,  the  car  of  which  is  the  canonical  name 
for  the  system,  and  the  edr  of  which  is  the  system  definition  body. 

1  sb ;  ‘sysdef s  Variable 

An  a-list  of  all  known  system  definitions.  ITie  car  of  each  entry  is  the  name  of  the 
system  (which  should  be  compared  using  LSB  token  equality),  and  the  edr  is,  if  non- 
atomic,  the  definition.  If  the  edr  is  atomic,  then  it  is  the  name  of  another  system  whose 
definition  should  be  used  instead  ("indirected  to”). 

lsb:*syslocs  Variable 

An  a-list  of  system  names  and  locations.  1116  location  here  is  exactly  that  supplied  with 
define-  system  -  location. 

Isb ; determlne-module-f lie-group  module-spec  sysiem-def 

system- def  \s  a  system  definition,  of  the  form  returned  by  lsb:establish-sysdef.  module- 
spec  is  the  entry  for  the  appropriate  module  out  of  the  modules  clause  of  the  system 
definition.  This  returns  a  representation  for  the  pathname  of  the  module  which  docs  not 
include  a  file-type  or  version;  this  is  used  for  such  things  as  finding  eitlicr  the  source  or 
compiled  output  file,  or  for  defaulting  the  pathname  for  a  diversion  stream  associated  with 
that  module. 

Isb;  determine -divers  Ion-filename  divstrcam-dausc  module- spec  system-def  version? 

Ihis  detennines  tlic  actual  pathname  for  the  diversion  stream  specified  by  divstream-clause, 
with  respect  to  module-spec  and  system-def,  using  a  version  of  version?,  module-spec  and 
system-def  are  the  same  as  for  lsb:determine-module-file-group.  divstream-clause  is  the 
clause  defining  a  diversion  stream,  version?,  if  not  nil,  should  be  the  version  to  be  used 
in  the  generated  filename. 

When  I.SB  itself  calls  this  to  determine  the  output  pathname  for  a  diversion  stream, 
version?  is  the  version  of  the  module  source  file,  module-spec  is  the  module-spec  of  the 
module  being  compiled,  and  system-def  is  the  system  definition  of  the  system  the  module 
is  a  part  of.  divstream-clause  is  whatever  Isbdind  divdef  would  return  for  module-spec 
and  system-def. 

When  1  .SB  calls  this  to  determine  the  input  pathname  for  a  diversion  stream  (say  a 
pubdcl  diversion  stream  to  be  loaded),  version?  is  nil.  In  llicory,  cither  it  could  be  the 
actual  version  of  tire  "installed"  source  for  the  module  in  question,  or  some  symbolic 
indicator  that  that  is  what  should  be  used,  l  or  input  it  is  assumed  that  an  unspecified 
version  does  something  reasonable  (typically,  retrieving  lire  "most  recent"  one). 
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1sb:f  1nd-d1vdef  Jivsi ream- name  module-spec  syslem-def 

I'his  looks  up  the  diversion  stream  definition  for  divsiream-name  for  module  module-spec  in 
system-def.  If  there  is  a  diversion-stream  defining  clause  for  divsiream-name  in  module- 
spec,  tliat  is  returned;  otherwise,  if  there  is  one  in  system-def,  that  is  returned; 
otherwise,  if  there  is  an  LSB  default  for  divsiream-name,  that  is  returned,  otherwise  nil. 

1sb:*d1vers1on-fn2s  Variable 

This  is  an  association  list  of  diversion  stream  names  and  their  default  file-types.  It  may 
need  to  be  hacked  if  cross-compilation  is  being  done.  Its  value  on  the  Lisp  Machine,  for 
example,  is: 

((pubdoc  .  pubdoq)  (sysdoc  .  sysdoq)  (moddoc  .  moddoq) 

(pubdcl  .  pubdql)  (sysdcl  .  sysdql)  (moddcl  .  moddql) 

(macros  .  maqros)) 

The  diversion  stream  names  arc  looked  up,  as  always,  using  LSB  keyword  equality. 

12.5  Inclusion  Tests 

A  non-atomic  inclusion  test  has  a  routine  associated  with  it.  When  the  inclusion  test  is 
performed,  this  routine  should  return  nil  if  the  text  enclosed  in  curly-brackcts  is  to  be  skipped 
over,  non-nil  if  it  is  not. 

12.5.1  Simple  Inclusion  Tests 

The  variables,  routines,  and  macros  described  here  should  be  sufficient  to  define  simple 
inclusion  test  routines,  such  as  only-for,  except-for,  only-on,  and  except-on. 

Isb:  *  implement  at  Ion- features  Variable 

1  his  variable  is  normally  nil.  If  it  is  set  non-nil,  then  it  is  used  as  the  set  of  "destination 
features"  used  by  the  only-for  and  except-for  inclusion  tests,  instead  of  the  result  of 
(status  features).  Note  that  the  only-on  and  except-on  inclusion  tests  always  use 
(status  features). 

Isb:  perform- Implement  at  ion-feature- tests  implemeniaiion-fealure-lests 

return-first- null-result?  return-first-non-null-result?  features- to- consider? 

This  is  the  routine  used  to  parse  implementation  feature  tests,  like  those  given  to  the 
only-for  inclusion  test.  If  feaiurey to- consider?  is  nil,  then  Isb:* implementation -features 
is  used  if  that  is  nut  nil.  otherwise  (status  features).  See  define-inclusion-test.  below. 

def ine-inclusion-test  Macro 

(define-inclusion-test  name  bvl 
fionn-l  form- 2  .  .  .  ) 

At  this  time,  the  function  defined  for  an  inclusion  test  gets  exactly  one  argument,  the  edr 
of  the  inclusion  test.  At  some  future  d.ite  it  is  anticipated  tltat  bvl  will  be  treated  in  some 
other  manner  so  ih.it  there  can  be  automatic  number-of-argument  checking.  Ihc  only-for 
inclusion  test  is  defined  as: 

( def ine  inclusion-test  only-for  (tests) 

(Isb: perform  -  imp lemen  tat i on -feature- tests 
tests  (  )  ’t  (  ))) 
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12.5.2  Environment  Modifying  Inclusion  Tests 

1.SR  keeps  a  stack  of  data  which  is  used  around  succeeding  conditional  inclusions.  This  is 
used  both  for  recording  the  location  of  the  initiating  lefl-curly-brackct,  and  for  possibly 
performing  some  specific  cleanup  action  when  the  right-curly-bracket  is  encountered. 

Isb: Input-file-status 

Returns  some  information  about  the  name  and  position  of  the  current  input  file. 
Normally  this  will  be  a  list  of  the  name  of  the  file,  and  the  current  file  position. 

1sb:*asynchronous-env1ronment-staclt  Variable 

This  is  the  stack  of  information  on  how  to  deal  with  all  currently  unmatched  left-curly- 
brackets.  Hach  entry  on  the  stack  is  a  cons  of  a  description  of  the  left-curly-bracket,  and 
how  to  undo  it.  The  latter  if  not  nil,  is  a  cons  of  a  function  to  apply  to  do  the  cleanup 
action,  and  the  arguments  to  apply  it  to.  The  default  action  performed  for  a  succeeding 
conditional  inclusion  is 

(push  (list  (list*  ( Isb: input-file-status) 

"conditional  inclusion  test" 
the- inclusion- lest) ) 

Isb: •asynchronous-envi ronment- stack ) 

If  an  inclusion  test  desires  to  manipulate  lsb;*asynchronous-environment-stack,  it  may 
do  as  as  shown  below,  and  instead  of  returning  just  any  non-nil  value,  it  should  return 
the  atom  lsb:*asynchronous-environment-stack  to  tell  the  caller  that  it  has  already 
performed  that  action.  For  example,  the  following  defines  the  gross -hack  inclusion  test 
(which  for  simplicity  ignores  its  arguments)  to  make  the  variable  ’gross-hack*  t  for  the 
duration  of  the  curly-brackets: 

( def ine-inc lusion-test  gross-hack  (ignore) 

(push  (list  (list  ( Isb : input-f i le-status )  "Gross  Hack") 
^'(lambda  (val)  (setq  ‘gross-hack*  val)) 
•gross-hack*) 

Isb: *asynchronous-envi ronment- stack ) 

(setq  ‘gross-hack*  t) 

' Isb : ‘asynchronous -environment-stack) 

12.5.3  Tex!  Diverting  Inclusion  Tests 

Icxt  diverting  inclusion  tests  arc  inclusion  tests  which  always  fail,  and  which  also  manage  to 
state  where  the  excluded  text  should  be  diverted  to.  The  simplest  way  for  tliis  to  be  done  is  with 
the  following  routines; 

1  Sb :  d  1  vert  -  to  - 1  Ust- of- dhersivn- stream- names 

rtiis  should  only  be  called  from  within  an  inclusion  test  which  is  going  to  return  nil. 
lsb;divert-to-1  itself  returns  nil  so  that  it  may  be  used  as  tlic  last  form  of  an  inclusion 
test  routine.  It  causes  tlic  excluded  text  to  be  transcribed  verbatim  U)  tlic  named  diversion 
streams.  Multiple  calls  may  be  made  to  lsb:divert-to-1  if  necessary;  specifying  a 
diversion  siream  multiple  limes  will  have  no  elicct.  For  example. 

( def ine- inclusion- lost  divert-my-lext  (ignore) 

( 1  sb  :  diver  t-to- 1  ’(m'-'c))) 

deliucs  ihc  inclusion  test  routine  diver  ■'v-text  such  that  (divert -my -text)  is  equivalent 
to  (divert  to  mydoc). 
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1  sb :  d1  vert-doc  - 1  list-of-diversion-stream-names 

This  is  just  like  lsb:divert-to-1,  but  additionally  defaults  Isb; ’diversion -routine  (see 
below)  to  a  routine  which  (1)  starts  the  diversion  output  on  a  fresh  line  while  (2)  flushing 
the  initial  newline  (if  any)  at  the  start  of  the  diverted  text.  Thus,  the  public- 
documentation  inclusion  test  could  have  been  defined  by 

( def ine-inclusion-test  public-documentation  (ignore) 

(  1  sb : di vert-doc- 1  '(pubdoc))) 

Note;  the  "-1"  suffix  on  the  preceding  two  routines  is  vestigial,  and  is  expected  to  disappear, 
someday. 

If  one  is  doing  complicated  textual  diversions,  such  as  those  done  by  document- routine,  the 
following  variables  may  be  hacked  by  the  inclusion  test  routine: 

1sb:*d1vers1on-b1nd1ngs  Variable 

This  is  an  a-!ist  of  variables  and  values  they  should  be  bound  to.  These  bindings  are 
cstablisiicd  around  the  diversion  of  the  text. 

1sb:*di  vers  ion -setup- forms  Variable 

A  list  of  forms  to  be  evaled  before  the  diversion  starts.  This  is  done  inside  the  binding 
environment  specified  by  Isb: ’diversion -bindings. 

Isb: ‘diver  si  on -cleanup- forms  Variable 

A  list  of  forms  to  be  evaled  after  the  diversion  finishes.  This  also  is  done  inside  the 
binding  entironment  specified  by  Isb; ’diversion -bindings. 

Isb: ‘divers  Ion -routine  Variable 

If  this  is  not  nil,  it  is  a  function  to  be  called  with  no  arguments.  It  has  sole 
responsibility  for  reading  and  diverting  tlie  text  between  matching  curly-brackcts. 

1  sb:  divers  Ion- tyo  charactercode 

Diverts  charactercode  to  all  of  the  diversion  streams  currently  being  diverted  to.  This  is  a 
special  case  of,  and  is  slightly  faster  than  doing  (lsb:diversion -operation  ’:tyo  character 
code). 

1sb:d1vers1on-operat1on  operation  (Any-number-of orgs) 

Sends  the  operation  message  to  all  of  tlic  diversion  streams  currently  being  diverted  to. 
I'he  operations  which  may  be  of  interest  inside  a  textual  diversion  are: 

:tyo  charactercode 

Outputs  the  single  character. 

;princ  object 

Docs  the  obvious. 

:prin1  object 
Ihis  too. 

:terpri 

This  too. 

;fresh-line 

IVrfomis  ,1  :fresh-line  operalitm  on  the  stream:  if  the  stream  is  not  al  the  shirt 
of  a  line,  then  a  newline  is  output. 
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Other  special-purpose  operations  may  be  defined  for  documentation  purposes,  such  as 
;start-operation-documentation;  see  the  discussion  on  documentation  types,  below. 

12.6  Denning  Documentation  Types 

The  squeamish  and  those  prone  to  heart  attacks  read  this  section  at  their  own  risk. 

Internally,  diversion  streams  use  a  relatively  simple  message-passing  mechanism.  A 
documentation  type  has  associated  with  it  a  function  which  can  field  some  subset  of  the  messages 
which  get  sent  to  documentation  diversion  streams;  if  it  docs  not  support  some  message,  the 
default  behaviour  (that  provided  by  simple  text  diversion  streams)  will  be  obtained.  The  function 
gets  a  first  argument  of  the  operation  name,  a  second  argument  of  the  output  stream,  and 
remaining  arguments  which  depend  on  the  operation.  It  should  thus  be  prepared  to  accept  any 
number  of  arguments.  Note  that  this  calling  convention  is  that  produced  by  a  function  defined 
with  the  l.isp  Machine  defselect  macro. 

Here  are  some  of  the  messages  a  documentation-type  handler  should  support: 

;which- operations 

The  handler  should  return  a  list  of  the  operations  it  supports.  That  list  need  not 
include  .which -operations,  but  :which -operations  must  be  handled.  The  result  of 
this  is  cached  by  tlic  diversion  stream  for  efficiency,  so  it  cannot  dynamically  change. 
1  iiis  operation  is  special  in  that  the  handler  may  be  called  on  it  before  the  stream  has 
been  created,  in  which  case  the  stream  argument  will  be  nil. 

■.start- operation  -documentation  data-list 

We  arc  starting  to  produce  some  operation  drKumentation.  as  gotten  from  document- 
routine.  data-lisi  is  a  list  of  datastructurcs  which  contain  the  information  for  each  of 
the  operations  being  documented;  see  <not-yet-writtcn>  for  using  tlicsc  datastructurcs. 
The  handler  should  output  whatever  is  neccssiiry  to  start  the  documentation;  for  Bolio, 
this  is  the  .defun  and  .defun  1  lines. 

:end  -  operation  -documentation  daia-lisl 

daia-lisi  is  the  same  as  for  -.start-operation-documentation.  The  handler  should 
"finish  up"  the  documentation  block. 

:start  -  variable  -  documentation  daia-lisi 

l  ike  .start -operation -documentation,  but  for  variables.  The  elements  of  daia-Ust 
are  in  a  dilfcrcnt  fonnat;  see  <not-yct-writtcn>. 

end  variable  documentation  data- list 

An.ilogous  to  :end  operation -documentation. 

More  operations  like  die  above  m,iy  be  added  in  the  fiiturc. 

Ilic  mcssrigcs  listed  above  arc  exactly  those  supported  by  the  bolio  and  tex  dtx;umcntation 
types.  It  is  possible,  however,  for  the  documentation  type  handler  to  have  much  finer  control 
over  the  output  which  is  produced,  boi  tltis.  it  needs  to  field  most  if  not  all  messages  which  arc 
passed  on  to  diversion  streams,  Ihese  arc: 

;tyo  choriH  icr-cddr 

Ihc  char.icter  should  be  output  to  tlic  strc.iin.  Ihe  information  on  whether  the 
dixiimentation  type  handler  fields  this  mcss.ige  is  c.iched  specially  for  clficiency. 
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:princ  object 

ITic  object  should  be  princcd  to  the  stream. 

;prin1  object 

ITtc  object  should  be  prinicd  to  the  stream. 

iterpri  A  newline  should  be  output  to  the  stream.  Note  that  newlines  in  text  being  diverted 
do  not  get  converted  to  terpri  operations,  but  are  left  as  whatever  charactcr(s)  they 
were  read  in  as.  Tlie  documentation  producing  routines,  however,  should  not 
generate  newline  character  sequences,  but  rather  use  the  :terpri  operation. 

:fresh-line 

A  newline  should  be  output  to  the  stream  iff  it  is  not  at  the  beginning  of  a  line. 

dab -to  destination  (Optional  increment) 

see  Jocuinentalion  on  the  ~T  operator  of  format 

;close  The  stream  should  be  "closed",  lliis  operation  is  only  used  for  successful  completion. 

:kill  The  stream  should  be  "closed",  and  aborted.  What  normally  happens  here  is  the 
stream  is  closed  and  the  partially  written  file  deleted. 

:open  pathname 

I'he  handler  can  support  this  if  it  desires  to  produce  a  non-standard  I/O  stream; 
normally,  open  would  be  called.  Note  that  if  the  .open  message  is  passed  to  the 
handler,  no  stream  has  yet  been  created,  so  the  stream  argument  to  the  handler  will 
be  nil.  I'he  handler  should  return  an  output  stream;  this  will  be  cached  by  the 
diversion  stream  mechanism,  and  passed  in  to  the  handler  for  all  subsequent 
operations. 

If  the  handler  is  going  to  field  character-level  stuff,  i.c.  the  :tyo  operation,  it  must  also  handle 
any  of  tlie  other  operations  which  may  produce  output  (sueh  as  :princ  and  :terpri);  the  default 
action  in  tlicse  cases  docs  not  involve  breaking  die  high-level  operation  into  its  components  and 
passing  them  back  to  the  handler.  In  Lisp  implementations  where  general  I/O  streams  are 
available,  it  is  probably  better  for  the  handler  to  field  the  :open  message  and  return  an  I/O 
stream  which  will  tlicn  handle  the  output  operations  appropriately. 

Finally,  if  one  is  willing  to  wade  through  all  of  tliis  and  needs  to  associate  a  function  with  a 
dcKumeniation  type  name: 

Isb:  •  documentation -types  Variable 

I  he  value  of  this  is  an  association  list  of  documentation  type  names  and  their  handler 
functions.  I'he  dtKumentation  type  names  arc  compared  using  1  .SB  keyword  equality. 

12.7  Macro  Mcmoization 
1sb:*macro-memo1zers  Variable 

I'his  is  an  a  list  of  keywords  acccpUtble  to  the  do- macro -memoizing  system  definition 
(.md  macro  decl.ir.iiiun)  clause.  Ihc  edr  of  each  entry  is  a  fiinction  whith  will  be  called 
to  produce  the  m.icro  meinoi/.ilion  code,  and  any  setup  code  which  must  come  before  the 
dclimiion,  Ihe  .iipiinieiits  are  the  ni.icro  name,  the  n.ime  of  Ihc  variable  which  will  have 
<is  its  \.iliie  Ihe  oiium.d  c.ill  form,  and  the  l()rm  which  will  need  to  be  evaluated  to 
produce  the  ev|r.msion.  The  function  should  return  a  list  of  forms.  I'he  first  form  will  be 
used  as  Ihc  bod>  of  the  macro,  and  I  SB  will  arrange  for  the  remaining  forms  to  precede 
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the  macro  definition  itself.  The  original  value  of  Isb:*  macro -memoizers  looks  like 

((t  .  Isb : standard-macmem)  (displace  .  1sb:d1sp1ace-macmem)) 
and  the  displace  method  of  macro  memoization  is  defined  by 
(defun  Isb : displace-macmem  (macro-name 

original-form-var 

new-form-form) 


macro-name  ;  maybe  unused 

'((displace  .original-form-form  , new-form-form) 
{(only-for  (or  PDP-10  NIL)) 

:  This  is  so  that  any  previous  form  of 
;  macro-memoization  will  revert  so  we  can  undo  it. 
(flush-macromemos  ’.macro-name  ())} 


)) 


Ml  ;l  SUIKK'.l  X  I  I;NI).17 


29-JLIN-8I 


LSB  Manual 


73 


Variable  Binding  ■  LBIND 


13.  Variable  Binding  -  LBIND 

The  LBIND  module,  although  not  a  part  of  the  default  LSB  environment,  is  closely  related 
to  it,  and  quite  useful  with  LSB,  both  to  supplant  the  use  of  the  bindq  and  auxiliary-bindings 
forms  in  operation  definitions,  and  in  places  where  those  forms  are  not  valid.  It  also  is  extremely 
useful  for  writing  implementation  independent  code,  as  the  data  types  of  the  variables  may  be 
specified  using  the  standard  LSB  data  type  keywords;  no  implementation  dependent  declarations 
are  needed.  If  it  is  used,  the  Ibind  system  should  be  noted  in  the  built-on  clause  of  the  system 
definition. 

Ibind  Macro 

Ibind  provides  let-like  syntax  for  binding  variables.  The  syntax  provides  for  the 
specification  of  data  types  rather  than  destructuring.  The  general  syntax  is 
(Ibind  {bind-spec- 1  bind-spec-2  ...) 
form- 1 
form-2 
...) 

A  bind-spec  is  one  of  the  following: 
variable 

Ihe  variable  will  be  bound  to  nil,  and  declared  to  be  of  type  notype. 

(variable  value-form) 

Ihe  variable  will  be  bound  to  the  value  of  value- form,  which  is  evaluated 
outside  the  binding  environment  of  the  variables.  It  is  declared  to  be  of  type 
notype. 

{{dala-lype  variable)  value-form) 

Ihe  variable  will  be  bound  to  the  value  of  value-form,  and  declared  to  be  of 
type  dala-lype. 

(variable) 

((dala-lype  variable)) 

((dala-lype  variable)  nil) 

An  unspecified  value-form  is  seen  simply  as  being  a  value-form  of  nil,  which 
causes  Ibind  to  detennine  die  initial  value  from  dala-lype.  Thus, 

(Ibind  (((fixnum  foo)  nil))  foo) 

=>  0 

because  foo  gets  bound  to  0  rather  than  nil. 

It  should  be  noted  tliat  a  bind-spec  for  Ibind  has  identical  syntax  to  that  of  the  auxiliary- 
bindings  form  recognized  in  operation  definition  bodies  (section  5.2.1,  page  28).  Thus, 
tlie  form 

(Ibind  (((fixnum  foo)  (mumble))  ((flonum  bar))  baz) 

...) 

==> 

((lambda  (foo  bar  baz)  ...) 

(mumble)  0.0  nil) 

along  with  local  declarations  for  the  typed  variables  appropriate  to  die  Lisp 
implementation. 
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In  many  cases,  one  would  like  to  compute  a  variable’s  value  as  some  function  of  other 
variables'  value.  For  this,  there  is  the  (bind*  macro: 

Iblnd*  Macro 

Ibind*  has  syntax  identical  to  Ibind.  The  bindings  are  nested,  however.  That  is, 

(Ibind  (((fixnuni  foo)  (mumble)}  ((flonum  bar))  baz) 

...) 

==> 

((lambda  (foo) 

((lambda  (bar) 

( ( lambda  (baz)  . . . ) 
nil)) 

0.0)) 

(mumble) ) 
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14.  Useful  LSB  Systems 

There  are  a  number  of  pre-defined  systems  in  LSB  whieh  may  be  of  general  interest.  Many 
of  these  are  not  written  using  LSB  (in  fact,  LSB  may  require  them  to  be  bootstrapped),  but  some 
have  LSB-style  definition  extensions. 

14.1  Pre-Defined  Systems 

Here  are  some  of  the  systems  which  are  pre-defined  (cither  with  define-system  or  define- 
system  -  location)  to  LSB.  This  list  is  incomplete;  the  full  list  is  in  the  file  ML;LSB;LSBSYS  >. 

format  The  Maclisp  implementation  of  the  format  function  is  written  using  LSB.  This  same 
source  will  be  used  to  bring  up  format  in  NIL.  The  Lisp  Machine  format  is  a  totally 
different  implementation,  although  the  major  public  definition  of  it  is  compatible, 
format  is  documented  in  the  Lisp  Machine  Manual  [LMMan],  and  documentation  of 
the  Maclisp  version  is  in  preparation. 

Brand -X-Triple 

Brand  X  is  a  low-level  extension  to  Lisp  for  use  in  building  knowledge  bases 
(HrandX).  It  is  written  using  LSB,  and  runs  in  PDP-10  Maclisp  and  Lisp  Machine 
Lisp. 

defstruct 

defstruct  is  a  structure  defining  facility  which  operates  compatibly  in  Maclisp  and  Lisp 
Machine  Lisp  (NIL?).  There  arc  LSB  definition  extensions  to  defstruct,  described 
later  in  this  chapter. 

loop  loop  is  a  hairy  iteration  macro  already  mentioned  [LOOP].  It,  like  defstruct,  has  LSB 
definition  extensions  which  arc  described  later,  loop  is  not  written  using  LSB;  being 
(built- on  loop),  however,  enables  a  system  to  not  only  use  loop  whether  or  not  loop 
is  accessible  by  default  in  the  given  Lisp  implementation,  but  also  gives  the  system 
access  to  the  LSB  definition  extensions. 

backquote 

sharpsign 

fhese  arc  for  tlie  backquote  ( ' )  and  sharpsign  ( )  reader  macros.  ITiese  exist  as 
systems  solely  for  the  Multics  implementation  of  LSB;  tlicy  arc  available  in  PDP-10 
Maclisp,  Lisp  Machine  Lisp,  and  NIL  by  default,  in  which  case  being  built-on  cither 
of  them  is  a  fast  no-op. 

Mathlab- Macros 

ITiis,  like  backquote  and  sharpsign,  exists  only  for  the  Multics  implementation  of 
l.SB.  Lsscntially,  it  comprises  all  of  the  various  utility  files  used  by  the  Mathlab 
group  on  Multics,  which  arc  not  covered  by  some  other  LSB  system  definition  (such 
as  backquote.  sharpsign,  and  defstruct).  It  includes  such  macros  as  setf,  if,  push, 
and  pop— most  of  the  tilings  which  arc  obtainable  by  default  in  PDP-10  Maclisp,  Lisp 
Machine  Lisp,  and  NIL. 

LSB  LSB  itself  h.is  a  system  definition  so  thiit  certain  internal  facilities  may  be  accessed  by 
users  if  necessary.  See  chapter  12.  page  63. 
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user -hunk 

A  low-level  PDP-10  Maclisp  interface  to  hooks  in  the  Lisp  for  treating  hunks  as 
extended-type  objects  [LSBUtilJ. 

ttyscan 

Fancy  parser-driven  rubout  processing,  for  PDP-10  Maclisp  only.  (Only  runs  on  ITS 
and  rOPS-20  systems.)  (LSBUtil] 

write  A  protocol  for  performing  text  output  which  can  be  used  to  build  such  things  as 
pretty-printers  [pp/writcj. 

pretty  -  print  -  definition 

A  layer  built  on  write  for  pretty-printing  Lisp  objects  [pp/write). 
pretty- print 

A  layer  built  on  pretty-print-definition  for  pretty-printing  Lisp  code  [pp/write]. 
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14.2  LOOP 

I.SIl  defines  tlic  following  extensions  to  the  loop  iteration  macro,  for  defining  iteration  paths. 

def  1ne-pub1  Ic-loop-path  Special  Form 
define -system -loop -path  Special  Form 
def  1  ne- private- loop  -  path  Special  Form 

Those  are  all  essentially  equivalent  to  define-loop-path,  but  arrange  for  the  infonnation 
to  be  sent  to  the  diversion  streams  necessary  for  appropriate  compilation  and  runtime 
support. 

def  Ine-publ  Ic-loop-sequence-path  Special  Form 
def  Ine- system- loop -sequence -path  Special  Form 
def  Ine- private -loop -sequence -path  Special  Form 
These  hack  define -loop -sequence -path  similarly. 

One  might  tlnis  do  the  following  to  define  a  public  loop  iteration  path: 

(  def  ine-pi'i  vate-routine  (  parse-my- loop-path  ...) 

(dels  ( a  1 so-needed-f or  public-compilation)) 

.  .  .) 

( def ine-publ ic-loop-path  my-loop-path  parse-my-loop-path  ...) 

Bccniisc  of  the  simplicity  of  the  define-loop-path  and  define-loop-sequence-path  fomis, 
if  it  is  necessary  to  divert  a  loop  patli  definition  somewhere  else,  the  forms -needed -for  special 
form  may  be  used 

( forms -needed- for  (running  public-compilation  hacks) 
(define-loop-path  ...)) 
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14.3  DEFSTRUCT 

defstruct  is  documented  in  the  Lisp  Machine  Manual,  and  documentation  of  the  Maclisp 
version  is  in  preparation.  On  the  ITS  systems  there  is  also  online  documentation  in  the  file 
LlBDOCiSfRUCI'  >. 

def  1ne-pub1 1c-structure  Special  Form 
define- system-structure  Special  Form 
def  1ne-pr1vate- structure  Special  Form 

'ITicse  arc  the  LSB  variants  of  defstruct.  'fhey  will  cause  the  structure  definitions  to  be 
available  at  runtime,  and  in  the  compilation  environment  (propagated  according  to  the 
visibility  class).  In  this  respect,  stmeture  definition  is  similar  to  macro  definition. 

The  arguments  to  these  forms  are  the  same  as  those  to  defstruct,  with  the  addition  of 
optional  LSB  declarations  clauses,  as  in  the  example 
(define- system -structure  (matrix 

( named) 

( def  aul t-poi nter ) 

( size -macro  matrix-structure- size) ) 
(dels  (reference  public)) 
matri x-array 
matrix-type 
matr i x-ncol s 
matrix-nrows) 

which  says  that  altliough  the  matrix  structure  has  a  visibility  class  of  system,  it  will  be  needed 
for  public  compilation.  I'his  might  be  because  there  is  an  opcn-codable-routine  or  a  macro  which 
expands  into  a  reference  to  tlie  matrix  structure.  The  declarations  allowable  here  are  those 
common  to  all  LSB  definitions:  the  definition  availability  declarations  (e.g.,  needed-for  and 
reference,  ),  and  other  similar  ones  like  divert-documentation-to. 

def  Ine-pubi  Ic-xstructure  Special  Form 
def  Ine-system-xstructure  Special  Form 
def  Ine-prlvate-xstructure  Special  Form 

These  are  just  like  the  corresponding  define- v/sc/ass -structure  forms,  but  divert  the 
structure  definition  tlie  way  the  define- v/sc/ow-xmacro  forms  do  (section  5.5.1,  page  34). 
That  is,  when  compiled,  the  definition  will  be  sent  to  the  macros  diversion  stream 
instead  of  tlie  compiled  output  file. 


2')-.lllN-Sl 


An  Example  System 


78 


LSB  Manual 


15.  An  Example  System 

ITiis  is  an  example  system  written  using  LSB.  Two  modules  arc  included  here,  with  some 
deletions  for  brevity. 


15.1  The  System  Deflnition 

This  is  tlie  contents  of  the  system  definition  file  for  the  stats  system,  which  is  in  the  file 
ML.S TA  rS;S  lAl’S  SYSI'EM.  riie  file  ML.SrA'IStSlATS  PKC  contains  the  package  definition 
for  the  statistics  package,  which  is  not  particularly  interesting.  Hic  source  code  is  assuming  only 
that  it  will  run  in  Lisp  Machine  Lisp  or  Maclisp.  Note  that  the  package  refnamc  stats  is 
equivalent  to  statistics. 

( def i ne-system  stats 
{(only-for  L1spm) 

(host  me) 

( device  ml ) 

} 

{(except-for  Maclisp) 

(package  statistics) 

} 

(directory  stats) 

( bui 1 t-on  loop) 

(type-check-visibility -classes  public) 

(modules  interpolate  ttable  ctable  ftable  normal)) 


15.2  The  INTERPOLATE  Module 

This  is  the  coinonis  of  the  interpolate  module,  which  is  in  the  file  MLiSTA  rS;IN  TERP  >. 
{  •-  Mode;Lisp;  t SB : i nterpol ate , stats  26-Jun-81 

Copyright  (c)  1981  by  Grandiose  System  Building 

and  Massachusetts  Institute  of  Technology.  All  rights  reserved.) 
(module  interpolate  stats) 

(  (  sy  s  tern  doi  iiiiinn  tat  ion) 

Ilie  (  1  i  II  lerpo  1  atei  *  module  defines  common  routines  to  allow 
trivial  definition  of  two - parame ter  statistical  functions. 

} 
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( def i ne-system-xmacro  (make-stat-table  dimension- 1 i st  init-list) 

(and  (atom  dimension-list) 

(setq  dimension-list  (list  dimension-list))) 

(bindq  (fixnum  impi ied-size)  (length  init-list) 

(fixnum  actual-size)  (apply  '*  dimension-list)) 

(and  (not  (=  implied-size  actual -si ze) ) 

(error  (if  (<  implied-size  actual-size) 

' I  Initial ization  list  has  too  few  entries! 

' I  Initialization  list  has  too  many  entries}) 

(list  'make-stat-table  dimension-list))) 

{(only-for  Maclisp) 

'(fillarray  (•array  nil  'flonum  .  .dimension-list)  ’.init-list) 

} 

{(only-for  Lispm) 

'(fillarray  (make-array  ’.dimension-list  ’:type  ’art-q) 

’  .init-list) 


} 


) 


{( document- routine) 

•  lisp 

(make-stat-table  cZdimension-l ist« •  eZinit-liste*) 

. end_l i sp 

expands  into  a  form  which  will  create  a  table  (implemented  as  an 
array)  which  will  contain  flonum  components  and  be  initialized  with 
the  elements  from  r 2 i ni t- 1 i stc* .  tZi n i t  - 1 i ste •  is  required  to 
contain  exactly  the  number  of  elements  required  to  fill  the  table. 
The  array  will  be  of  type  eSflonumr*  in  Maclisp,  but  a  normal  array 
(f3art-qf*)  on  the  Lisp  Machine  so  that  accessing  does  not  do 
additional  number  consing. 

} 

( def i ne-system-xmacro  ( stats : tabref  table  i  j) 

{(only-for  Maclisp)  ’(arraycall  flonum  .table  .i  ,j)} 

{(only-for  Lispm)  ’(aref  .table  .i  .j)}) 

{ ( document-routi ne ) 

.lisp 

( stats : tabref  rZtablee*  tZie*  eZje*) 

. end_l i sp 

accesses  a  two-dimensional  table  created  by  e3make-stat-tablee* . 

) 
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(define -system- routine  ( table- interpolate 

(fixnum  xl)  (flonum  vl) 

(fixnum  x2)  (flonum  v2) 

(fixnum  xprime)) 

(declarations  (value-type  flonum)) 

(+$  vl  (•$  (//$  (-$  v2  vl)  (float  (-  x2  xl))) 

(float  (-  xprime  xl))))) 

{(document- routine) 

This  calculates  the  value  corresponding  to  t2xprimef*  by  linear 
interpolation,  given  E2xlt*  and  £2vlt*.  and  t2x2£*  and  f2v2e*. 

} 

( def i ne- system- rout i ne  ( t ab 1 e- 2d im- lookup 

(fixnum  n)  (flonum  cf)  cf-list  basis-size 
more-n - val ues  infinity-index?  table  who) 
(dels  (value-type  flonum)) 

) 

{(document- routine) 

This  implements  the  basic  two-parameter  lookup.  £2n£*  is  the  number 
etc 
} 


15.3  The  TTABLE  Module 

{-•-  Mode:Lisp;  LSB : ttable , stats  -•-  9-Jun-81 

Copyright  (c)  1981  by  Grandiose  System  Building 

and  Massachusetts  Institute  of  Technology.  All  rights  reserved.} 
(module  ttable  stats) 
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(define-system-variable  ‘has ic-T-t able 


(init 

(make- 

stat-tablfl  (34. 

8.) 

: :  60% 

75% 

90% 

95% 

97.5% 

99% 

99.5% 

99.95% 

(0.325 

1.0 

3.078 

6.314 

12.706 

31.821 

63.657 

636.619 

:n=l 

0.289 

0.816 

1.886 

2.920 

4.303 

6.965 

9.925 

31.598 

:n=‘2 

0.277 

etc.  etc. 

0.765 

1.638 

2.353 

3.182 

4.541 

5.841 

12.924 

;  n=>3 

0.256 

0.683 

1.310 

1.697 

2.042 

2.457 

2.750 

3.646 

;  n  =  30 

0.255 

0.681 

1.303 

1.684 

2.021 

2.423 

2.704 

3.551 

;n  =  40 

0.254 

0.679 

1.296 

1.671 

2.000 

2.390 

2.660 

3.460 

:  n=60 

0.254 

0.677 

1.289 

1.658 

1.980 

2.368 

2.617 

3.373 

:n=120 

0.253 

)))) 

0.674 

1.282 

1.645 

1.960 

2.326 

2.576 

3.291 

;  n»i nf 

( def i ne-publ i c-routine  ( stats : t-table  (fixnum  n)  (flonum  cf)) 
(declarations  (value-type  flonum)) 

( table-2dim-lookup 

n  cf  ’(6000.  7500.  9000.  9500.  9750.  9900.  9960.  9996.) 

30.  ’(40.  60.  120.)  300.  ‘basi c-T-tabl e  ’ stats : t-table ) ) 

{(document -routine) 

This  implements  a  T-di stribution  lookup  for  degrees-of-f reedom  eZne* 
and  confidence-factor  e2cfe*.  €2cff*  may  be  either  a  fraction  or 
a  percentage;  they  can  be  distinguished  because  the  former  must  be 
less  than  €31. Oe*.  It  may  range  from  60%  to  99.95%. 

} 

15.4  The  Documentation  Produced 

Here  is  what  the  system  documentation  for  the  interpolate  module  looks  like  when 
formatted. 

The  interpolate  module  defines  common  routines  to  allow  uivial  definition  of  two-parameter 
statistical  functions. 

make-stat'table  Afacro 

(make-stat-table  dimension-lisi  initdist) 

expands  into  a  form  which  will  create  a  table  (implemented  as  an  array)  which  will 
contain  flonum  components  and  be  initialised  with  the  elements  from  inii-lisl.  mil-list  is 
required  to  contain  exactly  the  number  of  elements  required  to  fill  the  table.  ITic  array 
will  be  of  type  flonum  in  Maclisp,  but  a  normal  array  (art-q)  on  the  Lisp  Machine  so 
that  accessing  does  not  do  additional  number  consing. 

stats  rtabref  Macro 

(  stats  :  tabref  table  i  j) 

accesses  a  two-dimensional  Uible  cicated  by  make-stat-table. 
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tabic- 1nt«rpo1at«  (funumx/)  (flonum  v/)  (fixnumjc2)  (flonum  v2)  (fixnum  xprime) 

’['his  calculates  the  value  corresponding  to  xprime  by  linear  interpolation,  given  xl  and  v/, 
and  x2  and  v2. 

tab1e-2d1m-1oolcup  (fixnumn)  (flonum  c/)  cf-list  basis-size  more-n-values  infinity-index?  table 
who 

This  implements  the  basic  two-parameter  lookup,  n  is  the  number  of  degrees  of  freedom 
desired,  cf  is  the  confidence-factor;  if  it  is  less  than  1.0  then  it  is  assumed  to  be  a 
fraction,  otherwise  it  is  assumed  to  be  a  percentage,  table  should  be  a  two-dimensional 
table  created  by  make-stat-table.  The  first  dimension  indexes  different  n  values,  and  the 
second  different  cf  values.  It  is  assumed  that  some  low  range  of  n  values  are  complete, 
and  are  in  the  (1  -  n)th  components  of  the  table,  basis- size  is  the  greatest  n  for  which 
these  contiguous  entries  exist.  Other  n  values  may  be  sparse;  more-n-values  is  a  list  of  the 
other  n  values.  If  infinity-index?  is  not  nil,  then  it  should  be  the  value  of  n  which  is 
considered  to  approximate  infinity;  in  this  case,  table  should  have  one  additional  n  row 
(not  accounted  for  by  basis-size  and  more-n-values)  which  contains  the  cf  values  for  n  = 
infinity.  Values  of  n  below  infinity- index?  will  be  linearly  interpolated.  wAo  is  simply  used 
for  generating  errors,  and  should  be  the  name  of  the  caller.  For  example:  if  we  have 
data  points  for  n  from  1-30,  40,  60,  120,  and  infinity,  then  the  first  dimension  of  table 
should  be  of  size  34,  basis-size  should  be  30,  and  more-n-values  should  be  (40  60  120). 
infinity- index?  should  be  an  n  value  for  which  the  data  are  not  significantly  different  from 
those  for  infinity.  If  this  table  contains  data  for  confidence-factors  of  60%,  75%  90%,  95%, 
97.5%,  99%,  99.5%,  and  99.95%,  then  cf-list  should  be  (6000  7500  9000  9500  9750 
9900  9950  9995).  These  parameters  are  in  fact  those  used  by  the  stats:t-table  function, 
q.v. 

I'his  routine  always  returns  a  flonum,  obtained  by  linear  interpolation  from  the  points 
surrounding  the  desired  point. 


» 

\ 
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16.  Table  of  Abbreviations 

Here  arc  all  of  the  predefined  keyword  synonyms  defined.  Reasonable  suggestions  for 
additions  are  solicited. 

also  -divert-  reinitialization  -to 

also-divcrt-rcinit-to 
arg  u  ment  -  seq  uence 

argseq,  arg-sequence,  arg-seq 
auxiliary-bindings 

auxs,  aux-bindings 
built-along-side-of 

built-with,  built-beside 
declaration-diversion -stream 
dcl-divstream 
declarations  dels 
default-initialization 

default-init 
device  dev 

directory  dir 

diversion -stream 

divstream 

divert-documentation-to 

divdoc,  divcrt-doc-to 
divert-reinitialization-to 

divert-reinit-to 
document  -  routines 

dcKument-routine 
document  -  variables 

dcKumcnt-variable 

documentation-diversion -stream 
doc-divstream 

files  -  needed  -  for  -  compilation 

additional-filcs-nccded 
form  -diversion  -  stream 

form-divstream 
identifier  id 

initialization  init 

number -check -visibility -classes 

numbcr-chcck-visibility-class 
pathname  filename 

private-documentation 

inodulc-documcnUUion 
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quoted  unquoted 

referenced  -  at  -  visibility  -  class 
reference 

system  intrasystem 

system  -  compilation 

intrasystem-compilation 

system -documentation 

intrasystem-documentation 

textual  -  diversion  -  stream 

text-diversion-stream,  text-divstream 

type  -  check  -  argu  ments 

typc-chcck-argument,  check-arg,  check-args 

type  -  check  -  visibility  -  classes 

typc-check-visibility-class 

value -type  data-type 
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also-divcrt-reinitialization-to  Variable  Definition  Clause . 46 

also -needed -for  Definition  Clause . 8 

announce  System  Definition  Keyword . 15, 20 

any -number- of  Prototype  Call  Keyword. . 26,44 

applicable- routine-only  Routine  Definition  Clause. . 31 

argref  Function . 37 

argseq  Data  Type  Keyword. .  37,  38, 47 
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argseq -list  Function . 38 

argset  Function . 38 
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auxiliary-bindings  Special  Hack .  28,29,73 

bindq  Special  Hack . 29, 73 

body  Prototype  Call  Keyword . 26, 44 

built-along-sidc  -of  System  Definition  Keyword . 16 

built-beside  System  Definition  Keyword . 13,16 

built-on . 13 

built-on  System  Definition  Keyword . 16,19 

call  mapping . 26 

cal!  mapping  keywords . 26,  33 

Call  pnxressing . 4,  30 

character-code  Data  Type  Keyword . 47 

conditional  inclusions . 24 

data  types . 47 

data- type  Routine  Definition  Clause . 30 

data -type  Variable  Definition  Clause. . 45 

dcl-divstrcam  System  Definition  Keyword . 17,50 

declaration  diversion  stream . 49,  51 

declaration-diversion-stream  System  Definition  Keyword . 17,50 

declaration -divstream  System  Definition  Keyword . 17 

declarations,  in  routinc/macro  definition . 4 

declare- routine  Special  Form . 40 

declare-  variable  Special  Form . 46 

dcfault-dcfmition-from  Routine  Definition  Clause . 31 

default  -  init  I  'ariable  Definition  Clause . 45 

default- initiali/ation  Variable  Definition  Clause . 45 

define -inclusion -test  Macro . 67 

definc-lsh-nag-option  Macro . 65 

definc-lsh-option  Miuro . 64 

dcfinc-privatc-compile-time-macro  Special  Form . 35 

dcfmc-pii\ate-data-t\pc  Special  Form . 48 

dcrmc-pi  i\atc-loop  -patli  Special  Form . 76 
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dcfine-private-loop-sequence-path  Special  Form . 76 

dcfinc-private-macro  Special  Form . 33 

define -private- open -codable- routine  Special  Form . 32 

define -private- optimizer  Specia/ Form . 36 

define-private-routine  Special  Form . 29 

define-private-structure  Special  Form . 77 

define -private -variable  Special  Form . 45 

define-private-xmacro  Special  Form . 34 

define-private-xstructure  Special  Form . 77 

definc-public-compile-time-macro  Special  Form . 35 

definc-public-data-type  Special  Form . . . 48 

define -public -loop -path  Special  Form . 76 

dcfinc-public-loop-scquence-path  Special  Form . 76 

define -public- macro  Form . 33 

define-public-open-codable-routine  Special  Form . 32 

define-public-optimizer  Special  Form . 36 

define -public -routine  Special  Form . 29 

define -public -special -form  Special  Form . 36 

define-public-stRicturc  Special  Form . 77 

define -public -variable  Special  Form . 45 

dcfinc-public-xmacro  Special  Form . 34 

define- public -xstructurc  Special  Form . 77 

dcfine-systcm-compile-time-macro  Special  Form . 35 

dcfine-systcm-data-lype  5';7ec;a/ Form . 48 

define-sysicm-location  Macro . 11 

define -system -loop -path  Special  Form . 76 

define-systcm-loop-scqucnce-path  Special  Form . 76 

define -system -macro  Special  Form . 33 

define-systcm-open-codable-routine  Special  Form . 32 

definc-system-optimizer  Special  Form . 36 

define  -  sy  stem  -  routine  Special  Form . 29 

dcfine-systcm-stnicturc  Special  Form . 77 

defme-system- variable  Special  Form . 45 

define  sy  stem -xmacro  Special  Form . 34 

define-system-xstructure  Special  Form . 77 

dcrivability . 3 

device  System  DctinUnm  Keyword . 17 

device,  in  pathnames .  10 

direclones,  in  pathnames . ; . 10 

directoiv  S\ stem  Definition  Keyword . 17 

diversion  stream  file-types . 50 

diversion  streams . 49 

diversion  -stream  System  Definition  Keyword . 17,  51 

divert-d(Kiimcmalion-to  Inclusion  Tester . 55 

divert -forms -to  Special  Form . 52 

divert  -  remit  to  1  anahle  Definition  Clause . 45 

iliverl  leimtiali/ation-to  I  anahle  Dtfinitlon  Clause . 45 

divert- to  Inclusion  tester . 52 

do  arpiimciit- number -checking  Routine  Definition  Clause . 30 

do  -aiptiment-number-checkinp  System  Definition  Keyword . 15 
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do-argument-type-checking  Routine  Definition  Clause . 30 

do-argumcnt-type-checking  System  Definition  Keyword. . 15,30 

do- macro -memoizing  System  Definition  Keyword . 15,  39, 40,  71 

doc-divstream  System  Definition  Keyword . 17,50 

document- routine  Inclusion  Tester . 55 

document- routines  Inclusion  Tester . 55 

diKumcnt- variable  Inclusion  Tester . 56 

document- variables  Inclusion  Tester . 56 

d(x:iimcntation  diversion  stream . 49 

diKumentation-diversion-stream  System  Definition  Keyword . 17,50 

eval  diversion  stream . 51 

except  for  Inclusion  Tester . 24 

except- on  Inclusion  Tester . 25 

file -type,  in  pathnames . 10 

files-needed- for-compilation  System  Definition  Keyword . 16 

fixnum  Data  Type  Keyword . 37, 47 

flonum  Data  Type  Keyword . 47 

form  diversion  stream . 49 

form  diversion  streams . 51 

form -diversion -stream  System  Definition  Keyword . 17,50 

form-divstream  System  Definition  Keyword  .  ...  17,50 

fonns  -  needed  -  for  Special  Form . 8, 52 

host  System  Definition  Keynvrd . 17 

host,  in  pathnames . 10 

ibase  Variable . 14 

implement- as  Routine  Definition  Clause . 31,39 

implementation  feature  test . 24 

implicit  quoting . 30 

inclusion  test . 5, 14,  24,  52 

inclusion  tester. . 5,24 

inclusion -test -rcadtable  System  Definition  Keyword . 14,25 

inhibit-calling-sequcnce-optimization  Routine  Definition  Clause . 35 

inhibit-calling-sequencc-optimizations  Routine  Definition  Clause . 31 

inhibit- documentation -production  System  Definition  Keyword. . 15,51,56 

init  Variable  Definition  Clause . 45 

initialization  Variable  Definition  Clause . 45 

input-radix  System  Definition  Keyword . 14 

integer  Data  Type  Keyword . 47 

keyword  equality . 2 

keyword  synonyms,  table  of . 83 

keywords . 2 

lambda  optimization . 32 

Ibind  Macro . 73 

Ibind*  Macro . 74 

list  Data  Type  Keyword . 38, 47 

loop  Macro . .38 

Isb  -  load  Function . 22 

Isb; •asynchronous- environment- stack  Variable . 68 

lsb:*di\crsion-bindings  I'ariable  . 69 

lsb:*di\crsion-cleainip- forms  Variable . 69 
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lsb;*diversion-fn2s  Variable . 67 

lsb:*diversion-routine  Variable . 69 

lsb:*divcrsion-sctup-forms  Variable . 69 

!sb:*docun.cntation-types  Variable . 71 

lsb:*implcmentaiion-features  Variable . 67 

lsb:*inacro-mcnjoizers  Variable . 71 

lsb:*readtables  Variable . 65 

Isb:*standard-rcadtable  Variable . 65 

lsb:*sysdcfs  Variable . 66 

lsb:*syslocs  Variable . 66 

lsb;compiling-to-file?  Function . 51 

Isbxompiling?  Function . 51 

kb;dctcnnine-diversion- filename  Function . 66 

Isb’.dctcrmine-modulc- file-group  Function . 66 

Isb.divcrsion-operation  Function . 69 

lsb:divcrsion-tyo  Function . 69 

Isb:  divert -declarations?  Function . 51 

lsb:divert-doc-l  Function . 69 

Isb:divert- documentation?  Function . 51 

lsb;divcrt-to-l  Function . 68 

Isbiestablish-sysdef  Function . 66 

lsh;find-divdef  Function . 67 

lsb:input- file-status  Function . 68 

Isb: kwd- assoc  Function . 63 

lsb:kwd-bassoc  Function . 63 

!sb;kwd-cqua!  Function . 63 

Isbikwd-lookup  Function . 63 

lsb;kwd- member  Function . 63 

lsb:not-ci)mpiling?  Function . 51 

lsh:perform-impIementation-feature-tests  Function . 67 

lsb:push-pair  Macro . 64 

Isb: push -sym  Macro . 64 

lsb:U)ken- assoc  Function . 63 

Isb: token -equal  Function . 63 

lsh:tuken-lookup  Function . 63 

isb  token  member  Function . 63 

Kbeom  Function . 60 

maert'  mernoi/ation . 15,  39 

make  si  It  table  Macro . 81 

module  S  vsh  III  Definition  Keyword . 16 

module  specification .  18 

mt)dulcs . 1 

names,  in  pathnames . 10 

needed  for  Definition  Clause . 8 

needed  -  for  keywords . 8 

needed  for  eompil.ition  System  Definition  Keyword . 15 

needed  tor  user -compilation  System  Definition  Keyword . 15 

notype  Du/u  7)/ie  Kcy>yord. . 47 

number  Diii,i  Type  Keyword . 47 

nnber  clu\  k  -  visilhlity -chisses  System  Definition  Keyword . 15 
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one -or- more -of  Prototype  Call  Keyword . 26,44 

online -documentation  Inclusion  Tester . 55 

only -for  Inclusion  Tester . 24 

only -on  Inclusion  Tester . 25 

open  coding . 32 

operation . 26 

optimizer . 36 

optional  Prototype  Call  Keyword . 26 

package  System  Definition  Keyword . 14 

package  hacks . 12, 14, 15, 20 

packages . 4 

pathname  Clause . 18 

pathname  components . 17 

pathnames . 10 

pd\-\isi  Data  Type  Keyword . 37,39,41 

pdl- vector  Data  Type  Keyword .  37,39,47 

pcrform-calling-scquence-optimizations  Routine  Definition  Clause . 31 

primarily-applicablc-routinc  Routine  Definition  Clause . 31 

private- documentation  Inclusion  Tester . 55 

prototype  call . 4,26 

public-documentation  Inclusion  Tester . 55 

quoted  Prototype  Call  Keyword . 30,43 

rcadtable  System  Definition  Keyword . 14 

readtable  Variable . 25 

redefinition  Routine  Definition  Clause . 31 

reference  Definition  Clause . 9 

referenced-at- visibility-class  Definition  Clause . 9 

rest  Prototype  Call  Keyword . 26, 44 

rest  parameter .  26, 37, 47 

returnable  Routine  Definition  Clause . 30 

routine . 26,29 

routine  definitions . 29 

sequence  Data  Type  Keyword .  37,  38, 47 

si  :systcm  -  version  -  in  fo  Function . 21 

sideways  system  extension . 13 

slow -and -hairy  Routine  Definition  Clause . 31 

small-flonum  Data  Type  Keyword . 47 

special  form . 35 

stats:tabrcf  Macro . 81 

synonyms,  table  of . 83 

system -d(x:umcntation  Inclusion  Tester . 55 

systems . 1,3 

table -2dim- lookup  Function . 82 

table -interpolate  Function . 82 

temporary -list  Data  Type  Keyword . 39,47 

temporary -vector  Dm, i  Type  Keyword . 39,47 

text -diversion -stream  System  Definition  Keyword . 17,  50 

text-divstream  System  Definition  Keyword . 17,50 

textual  diversion  stream . 49,  52, 55 

tcxtual-divcrsion-strcam  System  Definition  Keyword. . '7,50,51 
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token  equality . 2 
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